Handbook

Scenario — Docs Health remediation

Reconcile /api/docs-health/* summaries and work items (GET-first) before handing fixes to Cursor agents.

Updated

Scenario summary

Reconcile /api/docs-health/* summaries and work items (GET-first) before handing fixes to Cursor agents.

User role

Docs Health operator or reviewer.

Starting state

Steps

  1. Read summary counts to learn whether issues are centralized or repo-specific.
  2. Pull work items sorted by severity; confirm repo slug paths match filesystem expectations.
  3. Pair each item with a human-readable Markdown path surfaced in payloads.

Example input / output

Do not paste production tokens; treat payloads as described in handbook tables plus sample-docs-health-work-item.json shape.

Expected intermediate state

Every accepted issue has an owner recorded before branching.

Verification

Feeds return HTTP 200 on localhost and align with Studio cards from First Docs Health scan.

Failure / recovery

If payloads disagree with cloned repos, re-run host scans (Workspace setup — scan host) and escalate before submodule edits.

Schemas and API for builders + sample-docs-health-work-item.json.

Canonical path

Still read Docs Health in Studio for UI-specific guidance alongside this API-first drill.