Recommendations

A recommendation is a concrete fix for a recurring pattern, either drafted by AI (POST /v1/ai/recommend/{pattern_id}) or created by hand. Every recommendation requires a fix_class (structural, compensating, or patch) and a pattern_id. Recommendations close the loop: Causeloop not only tells you what is broken and why, it tells you what to do — and then tracks whether the fix held. Recommendations are generated automatically when a pattern reaches sufficient confidence, and are ranked (rank = f(roi_pct, urgency(T̂_R), effort), a deterministic formula from the hazard config). The business_case behind the ranking — ale_avoided, roi_pct, and the counterfactual it’s coupled to — is always computed by Causeloop from the pattern’s fitted hazard and financials; it is never accepted as free-form client input.

The Recommendations list

Navigate to Recommendations in the left sidebar to open the ranked list.

Summary header

Three KPI tiles appear at the top:

Tile	Description
Open	Recommendations in `pending` or `in_progress` status
Loops preventable	Sum of `expected_loops_prevented` across open recommendations
Exposure addressed	Sum of `ale_avoided` across open recommendations — computed per-pattern from the fishbone rate-card and hazard counterfactual, not a flat per-loop constant

Ranked rows

Each row shows:

Rank — deterministic ranking (rank = f(roi_pct, urgency(T̂_R), effort); rank 1 = highest priority)
Title — the recommended action
Type chip — code_fix, config, process, or monitoring
Fix class chip — structural, compensating, or patch
Impact pill — high, medium, or quick_win
Effort chip — EFFORT LOW, EFFORT MED, or EFFORT HIGH
Status pill — pending, in progress, implemented, or dismissed
Expected loops prevented — computed from ale_avoided and the counterfactual, not a free-text AI estimate

Filtering and sorting

Use the filter bar to narrow by:

Parameter	Options
`type`	`code_fix`, `config_change`, `process`, `monitoring`
`fix_class`	`structural`, `compensating`, `patch`
`status`	`pending`, `in_progress`, `implemented`, `dismissed` (comma-separate for OR)
`impact`	`high`, `medium`, `quick_win`
`sort`	`rank` (default), `-rank`, `-created_at`, `-expected_loops_prevented`, `-updated_at`

Recommendation detail

Click any row to open the recommendation detail page at /recommendations/{id}. The header shows:

Eyebrow — RANK #{n} · {type} · CREATED {date}
Title — the full recommendation title
Impact pill and status pill
Pattern chip — the source pattern this recommendation addresses

Top-bar actions: Push to tracker, Mark implemented.

Overview (left column)

The Overview card contains a plain-language summary of what the fix does and why it prevents the loop from recurring.

Implementation plan (left column)

Below the overview, the Implementation plan card lists the AI-generated steps needed to apply the fix. Each step has a title, a description, and a completion checkbox. As you complete steps, check them off — the progress is saved per step.

Source pattern (right rail)

The Source pattern rail card shows the pattern this recommendation was generated from: name, pattern ID, issue count, and risk score. Click Open pattern → to navigate to the pattern detail page.

Addresses N issues (right rail)

This card lists the specific issues that this recommendation, once applied, will address. Each row shows the external ID and a risk score.

On implementation (right rail)

A note card explains what happens after you mark this recommendation implemented:

The pattern enters its 90-day hold window. If no recurrence, status flips to Held and a regulator-ready attestation is generated.

Acting on a recommendation

Pushing to your issue tracker

Before starting implementation, queue the recommendation for delivery to your team’s issue tracker.

Open the recommendation detail

Navigate to the recommendation you want to act on.

Click Push to tracker

A dialog appears with fields for the target tracker and project key.

Choose your tracker and project

Supported trackers: Jira, Linear, GitHub, ServiceNow. Enter the project key (e.g. ENG).

Confirm

The push is queued against the connected tracker connector.

The push is handled by POST /v1/recommendations/{id}/push.

Causeloop does not yet create a real ticket in the external tracker — there is no tracker connector call wired up to produce a real ticket number or URL. A successful push returns {"queued": true, "external_ref": null, ...}, and the recommendation’s tracker reference carries external_id: null / external_url: null. This is intentional: Causeloop never fabricates a ticket ID or URL it did not actually receive from the tracker. If the workspace has no connected connector of the requested tracker type, the push fails outright with 409 tracker_not_connected instead of silently queuing against nothing — connect a tracker connector under Settings → Connectors first.

Marking implemented

Once you have applied the fix, mark the recommendation as implemented.

Click Mark implemented

The button is in the top bar of the recommendation detail page.

Confirm

The recommendation status changes to implemented. The linked pattern enters the 90-day hold window immediately.

You can also use PATCH /v1/recommendations/{id} with status: "implemented". The analyst role is required.

Attesting the fix held

After 90 days without recurrence, the pattern’s attestation_ready flag is set to true. At that point you can formally attest that the fix held.

Navigate to the recommendation detail

The detail page shows an attestation prompt when attestation_ready is true.

Click Attest

Enter attestation notes and optional evidence URLs (links to PRs, run logs, or audit records).

Submit

An attestation record is created with attested_by, attested_at, notes, and evidence_urls. This record is available for audit and compliance exports.

The attestation is stored via POST /v1/recommendations/{id}/attest. Retrieve the attestation record at any time with GET /v1/recommendations/{id}/attestation. Attesting also starts statistical monitoring, not just the 90-day clock. GET /v1/recommendations/{id}/verification returns the live state (monitoring, verified, failed, or not_started), the CUSUM statistic and its trajectory against the target intensity reduction (taken from the hazard counterfactual), and the expected decision window. An admin can force-close monitoring with POST /v1/recommendations/{id}/verification/close. When the fix is verified or fails, the fix.verified / fix.failed event updates the theme’s persistence term (Sh) for the next engine run and fires notifications — this is the product’s proof-of-value artifact.

Attesting a dismissed recommendation requires you to re-open it first (move status back to pending or in_progress).

Proof-window verification

The Remediation view shows every recommendation currently in — or that has completed — a proof-window verification lifecycle across the workspace, so you don’t have to open each recommendation one at a time. GET /v1/recommendations/verifications returns:

{
  "data": [
    {
      "rec_id": "rec_01hx...",
      "title": "Add idempotency key to payment webhook handler",
      "pattern_id": "pat_01hx...",
      "pattern_name": "Duplicate payment webhook processing",
      "fix_class": "structural",
      "status": "in_window",
      "window": { "total_days": 90, "elapsed_days": 12.4, "started_at": "2026-06-20T14:03:00Z" },
      "progress_pct": 13.8,
      "live_metric": { "current": -1.2, "decision_boundary": 4.0, "cusum_pos": 0.0, "cusum_neg": 1.2, "trajectory": [] },
      "reopened": false,
      "closed_at": null,
      "outcome": null
    }
  ],
  "summary": { "in_window": 4, "holding": 1, "reopened": 0, "verified": 9 }
}

status is one of four lifecycle buckets, all derived from stored fields — never wall-clock guesses:

Status	Meaning
`in_window`	Monitoring, within its expected decision window
`holding`	Still monitoring, but past the upper bound of its expected decision window — overdue for a decision
`reopened`	The CUSUM statistic crossed its negative boundary — the fix did not hold
`verified`	The CUSUM statistic crossed its positive boundary — the fix held

GET /v1/recommendations also embeds a light verification summary ({status, progress_pct, reopened} or null) on each row, so the list view can show fix-plan state without an extra call per recommendation.

Dismissing a recommendation

If a recommendation is not applicable to your context, dismiss it with a reason:

PATCH /v1/recommendations/{id}
{
  "status": "dismissed",
  "dismissal_reason": "Third-party service handles this — not in scope."
}

dismissal_reason is required when setting status to dismissed.

Status transitions

From	Allowed transitions
`pending`	`in_progress`, `dismissed`
`in_progress`	`implemented`, `pending`, `dismissed`
`implemented`	— (terminal; use attestation flow)
`dismissed`	`pending`

API reference

Endpoint	Description
`GET /v1/recommendations`	List recommendations with filters (default `sort=rank`); each row embeds a light `verification` summary
`POST /v1/recommendations`	Create a recommendation — requires `fix_class` + `pattern_id`; `business_case` is always computed, never client-supplied
`GET /v1/recommendations/{id}`	Get recommendation detail
`PATCH /v1/recommendations/{id}`	Update status, impact, or dismiss
`POST /v1/recommendations/{id}/push`	Queue a push to an issue tracker — `409 tracker_not_connected` if none is connected; otherwise `{queued: true, external_ref: null}` (no fabricated ticket)
`GET /v1/recommendations/{id}/plan`	Get the structured implementation plan
`POST /v1/recommendations/{id}/attest`	Attest that the fix held (also starts verification monitoring)
`GET /v1/recommendations/{id}/attestation`	Retrieve the attestation record
`GET /v1/recommendations/{id}/verification`	Live verification state, CUSUM statistic, and decision window
`POST /v1/recommendations/{id}/verification/close`	Admin override to close monitoring
`GET /v1/recommendations/verifications`	Remediation view — every verification lifecycle in the workspace, flat list + summary counts
`GET /v1/recommendations/stats`	Aggregate stats, derived from business cases (no flat per-loop constant)

Patterns

See the pattern a recommendation is addressing.

Predictions

Understand the recurrence risk driving each recommendation.

Issues

See the issues a recommendation addresses.

Reports

Include recommendation coverage in an executive report.

Working in Causeloop

Settings & Administration

The Recommendations list

Summary header

Ranked rows

Filtering and sorting

Recommendation detail

Header

Overview (left column)

Implementation plan (left column)

Source pattern (right rail)

Addresses N issues (right rail)

On implementation (right rail)

Acting on a recommendation

Pushing to your issue tracker

Marking implemented

Attesting the fix held

Proof-window verification

Dismissing a recommendation

Status transitions

API reference

Patterns

Predictions

Issues

Reports

​The Recommendations list

​Summary header

​Ranked rows

​Filtering and sorting

​Recommendation detail

​Header

​Overview (left column)

​Implementation plan (left column)

​Source pattern (right rail)

​Addresses N issues (right rail)

​On implementation (right rail)

​Acting on a recommendation

​Pushing to your issue tracker

​Marking implemented

​Attesting the fix held

​Proof-window verification

​Dismissing a recommendation

​Status transitions

​API reference

​Related pages

Patterns

Predictions

Issues

Reports

The Recommendations list

Summary header

Ranked rows

Filtering and sorting

Recommendation detail

Header

Overview (left column)

Implementation plan (left column)

Source pattern (right rail)

Addresses N issues (right rail)

On implementation (right rail)

Acting on a recommendation

Pushing to your issue tracker

Marking implemented

Attesting the fix held

Proof-window verification

Dismissing a recommendation

Status transitions

API reference

Related pages