Backlog intake

You are triaging a batch of deep-review artifacts into ai_docs/backlog.md. Your job is to turn raw audit / retro / experimental-promotion markdown files into properly-sized, anchor-verified, de-duplicated, priority-ranked rows that /backlog-remediate can route without re-processing.

This skill replaces the eng/new-deep-review-batch.ps1 → sync-deep-review-backlog.ps1 pipeline. The PowerShell pipeline handled only *_mcp-server-audit.md, did literal-text dedupe, and couldn't verify anchors or size rows to Rule 1/3/4. The judgment work belongs in an LLM; the mechanical file-staging is delegated to eng/stage-review-inbox.ps1.

v15 backlog boundary

Raw external-source severity is metadata, not a local backlog priority. Map it only as follows before materializing a local row:

Raw external-source severity maps only as P0 -> Critical, P1 -> High, P2 -> Medium, and P3 -> Low.

No raw source severity maps to Defer. Emit only Critical, High, Medium, or Low in an actionable local row; preserve the raw value in source evidence or public-issue metadata when it matters.

Every mutation of ai_docs/backlog.md, its paired ai_docs/items/<id>.md files, its preamble, or its updated_at stamp uses the global writer: node ~/.claude/scripts/backlog.mjs <subcommand> <repo-root> …. Use add for a new row/detail pair, update for an existing slim row, note for an existing detail file, preamble-replace for one verified preamble replacement, and touch only when no row changed. The writer transactionally lint-checks, synchronizes the row/detail pair, and bumps updated_at; if it exits nonzero, stop that mutation and retain the source artifact. Do not hand-edit, append, re-sort, or count the backlog table. Derive the final count only with node ~/.claude/scripts/backlog.mjs count <repo-root>.

Moving staged reports and deleting a consumed source fragment are artifact operations, not local backlog writes. Do them only after the corresponding writer transaction succeeded, or after an exact duplicate match was recorded with no local mutation; never delete evidence to compensate for a failed or rolled-back writer call.

Server discovery

This skill edits repository files, shells out to pwsh / gh / git, and uses Roslyn MCP read-only tools (symbol_search, find_references, get_source_text) to verify anchors. No Roslyn MCP *_apply / *_preview writers are allowed. The global backlog.mjs writer is the required local-backlog exception described above; any other direct backlog writer is a stop-and-hand-back error.

Input

$ARGUMENTS is optional. Supported flags:

Default (no flags): stage if review-inbox/ is empty, verify against CHANGELOG, commit to a fresh branch off main.

Preconditions (HARD GATES — refuse if any fail)

1. `git` CLI on PATH. If not, refuse.
2. `pwsh` CLI on PATH (used by the staging script). If not, refuse.
3. Working tree clean OR the only dirty paths are review-inbox/, ai_docs/backlog.md, and the paired ai_docs/items/<id>.md files intake owns. If other paths are dirty, refuse: "Working tree has unrelated changes — commit or stash before intake."
4. `main` up to date with `origin/main` (git fetch origin main first). Refuse if main diverged in a way that requires manual resolution.
5. `ai_docs/backlog.md` exists with ## Critical, ## High, ## Medium, ## Low, ## Defer, and ## Refs. If the file is missing or shape-wrong, refuse: "backlog.md shape is unexpected — run /doc-audit initial before re-running this skill."
6. Unless --no-commit is set, create chore/backlog-audit-intake-{YYYYMMDD} from the verified clean, current main before the first writer transaction. Do not switch branches or pull after intake-owned writes begin.

Workflow

Phase 0 — Stage artifacts

Skip this phase if --skip-stage is set.

eng/stage-review-inbox.ps1 discovers artifacts from this repo and configured siblings. The canonical list of recognized shapes lives in that script's .DESCRIPTION → Recognized shapes block — read it there; do not re-list the globs here. Those shapes fall into TWO handling categories:

1. Prose audit / retro / promotion reports — moved into review-inbox/ for the existing extraction flow.
2. `backlog.d/<finding-id>.md` fragments — discovered at <sibling-repo-root>/backlog.d/*.md and at this repo's backlog.d/. Disambiguated from prose reports by the severity: frontmatter key; canonical schema at ai_docs/items/backlog-d-fragment-schema.md.

pwsh -File eng/stage-review-inbox.ps1 -DryRun

Review the dry-run output. If the file list looks right:

pwsh -File eng/stage-review-inbox.ps1

If --stage was passed OR review-inbox/ is empty at the start of the run, also run the real command. If the PS1 finishes with "No new artifacts found" AND review-inbox/ is empty AND no `backlog.d/` fragments exist anywhere, refuse: "Nothing to triage. Produce audits first via /mcp-server-stress (bundled prompt at .claude/skills/mcp-server-stress/prompts/maintainer-overlay.md), then re-run."

Record the count: N reports + F fragments staged from M repos for the final summary.

Phase 0.5 — Consume fragments (backlog.d/ pattern)

Fragments take a different path from prose reports. They are not moved into review-inbox/; instead intake reads them in place from each source repo's backlog.d/, dedupes, materializes local rows through backlog.mjs, and deletes the consumed fragments at the source. The deletion IS the consumption record — there is no manifest file.

For each configured sibling repo (and this repo) with a backlog.d/ directory:

1. Walk <repo>/backlog.d/*.md. For each file, parse YAML frontmatter; require id, source_audit, source_repo, severity, area, server_version, anchors (per ai_docs/items/backlog-d-fragment-schema.md). If any required key is missing OR severity / area is outside the documented enum OR anchors is empty OR the filename does not match id, skip that fragment with a warning — leave it on disk for the audit operator to fix. Do NOT delete malformed fragments.
2. Dedupe each remaining fragment against existing ai_docs/backlog.md rows in this order:

• Exact `(source_repo, id)` match — if a backlog row already cites the same source_repo and the same row id, the fragment is a duplicate. Record the exact match, drop it from the candidate list, then delete the source fragment (the row already represents this finding).
• Anchor-set similarity — compare each fragment's anchors against existing rows. When ≥50 % of anchor paths overlap on the same shared code (typical for cross-repo audits hitting the same Roslyn-MCP server bug from two reporters), prepare the merged v15 do cell and any detail note, then call backlog.mjs update and backlog.mjs note as needed. Delete the source fragment only after those writer calls succeed.
• Already-shipped check — same Phase 2 logic that runs on prose-report candidates (CHANGELOG / recent plans / git log).

1. Materialize any non-duplicate, non-shipped fragment with backlog.mjs add, passing the mapped v15 --pri, a slim --do-file, and one --items-file. Use the body paragraph (finding + repro + proposed fix sketch) as the seed; do not write a table row directly.
2. Delete each source fragment with git rm (when the sibling repo is git-tracked) or Remove-Item (when it is not) only after its duplicate match is confirmed or its writer call succeeds. Re-resolve the exact file beneath that sibling's backlog.d/ immediately before deletion; do not use a glob. Track deletions for the final commit message.

Idempotency contract: re-running intake on a clean backlog.d/ (no fragments, or only fragments already represented in ai_docs/backlog.md) is a no-op. The deletion is what makes this true — once consumed, the fragment is gone, so the next pass sees nothing to consume.

Cross-repo mutation note: intake mutates audited sibling repos by deleting fragments under their backlog.d/. This is intentional — it is how the consume-and-track pattern works without a manifest file. The audited repos' authors are expected to be aware that intake has this side effect; if a sibling repo wants to retain a record of what was reported, the prose *_mcp-server-audit.md under its ai_docs/audit-reports/ is preserved and acts as the historical record.

The existing prose-report ingestion flow (Phases 1–6) continues unchanged for review-inbox/*.md artifacts. Fragments and prose reports coexist; they are not mutually exclusive.

Phase 0.6 — Consume aggregated promotion scorecard proposals

If audit-reports/_aggregated-promotion-scorecard.json exists, run:

pwsh -NoProfile -File eng/propose-promotion-scorecard-backlog-rows.ps1

This script is read-only: it emits stable backlog-row proposals for aggregated promotion-scorecard entries whose verdict is promote: blocked or needs-more-evidence, and it lists promote: ready entries as skipped so they continue through /promote-tier.

For each proposal:

1. If action == "add-new", materialize the emitted id, v15 pri, deps, and

slim do text with backlog.mjs add and an --items-file when the row touches code.

1. If action == "update-existing", call backlog.mjs update --do-file only when

the proposal contains new blockers, source repos, or rationale that the row does not already mention; use backlog.mjs note for evidence that belongs in its detail file.

1. Preserve idempotency: rerunning the script after a row is represented must

produce update-existing, not a duplicate row.

1. If you intentionally skip a proposal, add a maintainer-readable note to the

final summary explaining why it was skipped. Do not silently drop blocked or needs-more-evidence scorecard entries.

The generated do cell cites audit-reports/_aggregated-promotion-scorecard.json; keep that anchor unless you move the scorecard into a different durable location as part of the same batch.

Phase 1 — Extract actionable items (subagent)

Invoke the dedicated backlog-intake-extractor subagent:

Agent(subagent_type: "backlog-intake-extractor", prompt: <<<
reviewInboxPath: <absolute path to review-inbox/>
existingBacklogPath: <absolute path to ai_docs/backlog.md>
>>>)

The agent encapsulates the extraction / filter / dedupe / classify / cross-check flow with a strict Read/Glob/Grep tool policy (no writers) and returns a <<<RESULT>>> envelope containing the deduped row list + notes. See .claude/agents/backlog-intake-extractor.md for the agent's own contract.

Parse the envelope. Capture dedupedRows / dedupeRatio / rawCandidates for the Phase 7 summary. Capture the row list for Phase 2.

Fallback (environments without .claude/agents/ support): spawn a general-purpose subagent and inline the agent's body as the prompt. The agent file is the canonical source of that prompt.

Phase 2 — Verify-not-already-shipped

Skip this phase if --skip-verify is set.

For each candidate row, cross-check:

1. `CHANGELOG.md` [Unreleased] + last 3 versions — grep for the tool name, service, or symbol the row cites.
2. Newest remediation plan under ai_docs/plans/*_backlog-remediate/ — read its state.json and plan.md. Also inspect *_backlog-sweep/ when historical compatibility evidence is relevant. Does any shipped initiative describe the same fix?
3. Git log, last 100 commits — git log --oneline -n 100 | grep -i <keyword> on tool / service / symbol names.
4. Code spot-check for rows flagged by 1-3 — open the named service / tool file and confirm the specific behavior still reproduces. For example, if the row says symbol_search("") overflows, grep SymbolSearchService.cs for an empty-query guard.

Don't spot-check every row's code — only the ones where prior evidence suggests the fix may have landed. Budget: ~1 minute per candidate flagged, ~0 for rows with no CHANGELOG / plan / log hit.

If this phase finds a row already shipped, drop it from the candidate list and record "dropped (already shipped per <evidence>)" in the final summary.

Phase 3 — Fix anchors

For each remaining row, verify every service class, tool file, and file:line anchor resolves:

1. For service-class names (e.g. DeadCodeService, CodeActionService): confirm the .cs file exists at the cited path. If the row says src/RoslynMcp.Roslyn/Services/FooService.cs but only src/RoslynMcp.Roslyn/Services/BarService.cs exists, prepare revised do text that cites the real file. Common mistakes the extraction subagent makes:

• CodeActionsService (plural) → actual is CodeActionService.cs
• MoveTypeService → actual is TypeMoveService.cs
• SemanticSearchService → logic lives in CodePatternAnalyzer.cs
• Hallucinated ServerInfoService / PackageReferenceService / RevertService — tools-layer-only, see src/RoslynMcp.Host.Stdio/Tools/ or the unified service (e.g. UndoService.cs for revert).

1. For tool registrations (e.g. find_references_bulk): grep src/RoslynMcp.Host.Stdio/Tools/ for Name = "<tool_name>" and cite the real file + line. The PS1 pipeline NEVER did this; it's a distinctive value-add of this skill.
2. For file:line references (e.g. CompileCheckService.cs:155): run get_source_text on that span to confirm the referenced code is still there.

Prepare each row's revised do text to cite both the core service (under src/RoslynMcp.Roslyn/Services/) and the tool registration (under src/RoslynMcp.Host.Stdio/Tools/). Materialize a new row with backlog.mjs add --do-file or refine an existing row with backlog.mjs update --do-file; do not edit the table directly. Executors can then land on the right file immediately.

If an anchor genuinely cannot be resolved, prepare do text tagged with [stale — cited anchor not found; executor may use synthetic examples] per the /backlog-remediate anchor-verification contract, then persist it through the applicable writer command rather than dropping the row.

Phase 4 — Split heroic rows

Apply the /backlog-remediate initiative-sizing contract to each row. A row is heroic (and must be split) if any of:

• It describes two or more distinct bugs that live in different code paths (different functions, different files).
• It asks for more than 4 production-file edits to fulfill.
• Its regression tests are not trivially-additive variants of one shape.
• Its "do" field contains a numbered "(1) fix A, (2) fix B, (3) fix C" list where each item is a different code change.

Common heroic shapes to watch for:

For each split, give each child a distinct kebab-case id (prefix with the original id where readable — e.g. scaffold-test-preview-dotted-identifier / -static-target-body / -ctor-arg-stubs).

Phase 5 — Ensure planner-prompt refs

Before a transactional mutation, verify the Refs table in ai_docs/backlog.md includes these entries. Add a missing one only through one exact backlog.mjs preamble-replace call. Note: the remediation contract is NOT a repo Refs entry — it lives globally in ~/.claude/prompts/backlog-remediate.md and ~/.claude/prompts/backlog-remediate-rules.md, so do NOT add repo-local rows for it:

Phase 6 — Persist through the writer, archive processed files, commit

1. Generate BATCH_ID in the form YYYYMMDDTHHMMSSZ from current UTC before the first writer transaction. It names the archive directory only; do not write updated_at manually.
2. Build each accepted row's slim do text and, when needed, its detail file before its writer call. Use the target review-inbox/archive/{BATCH_ID}/<file> citation in the generated text, then use backlog.mjs add, update, or note for every local row/detail change. Do not edit or re-sort the table. The successful transaction owns the updated_at bump.
3. Ensure the "Standing rules" section includes the initiative-sizing rule through one verified backlog.mjs preamble-replace call when it is missing: "Size every row to a single /backlog-remediate initiative: one code path, ≤4 production files, ≤3 test files, one regression-test shape." If any writer call fails or rolls back, stop and retain its source report or fragment for a later retry.
4. Archive the processed review files only after all associated writer calls succeed. Only move files that produced accepted rows this batch — do NOT touch any existing review-inbox/archive/<prior-batch>/ subdirectories.

   mkdir -p "review-inbox/archive/${BATCH_ID}"
   for f in review-inbox/*.md; do git mv "$f" "review-inbox/archive/${BATCH_ID}/$(basename "$f")"; done

The flat review-inbox/ directory is now empty (save for the archive/ subdirectory) and ready for the next batch to stage into.

1. For a pre-existing row whose citation must change, use backlog.mjs update --do-file before the move. This keeps anchors resolvable after the archive without a direct table edit.
2. Verify the Refs table in ai_docs/backlog.md describes both the flat review-inbox/ (staging) and review-inbox/archive/<batch-ts>/ (processed evidence) roles. Use backlog.mjs preamble-replace for any correction; the flat directory is always the next batch's inbox.
3. Read the final count with node ~/.claude/scripts/backlog.mjs count <repo-root>. Skip the commit if --no-commit; otherwise:

   git add -- ai_docs/backlog.md review-inbox/ ai_docs/items/<id>.md [additional-exact-item-paths]
   git commit -m "..."

Commit message template:

   chore(backlog): intake cross-repo audit + retro batch ({YYYY-MM-DD})

   Consolidates actionable items from {N} review files across {M} repos into
   ai_docs/backlog.md. Archived processed files under
   review-inbox/archive/{BATCH_ID}/ so the flat review-inbox/ stays empty for
   the next batch.

   Backlog now: {output from `node ~/.claude/scripts/backlog.mjs count <repo-root>`}.
   Rows anchored to both core services (src/RoslynMcp.Roslyn/Services/)
   and tool registrations (src/RoslynMcp.Host.Stdio/Tools/) so first executor lands
   on the right file without a scavenger hunt.

   - Splits applied: {list of heroic rows that were split}
   - Dropped (already shipped): {list, if any}
   - Verified against CHANGELOG [Unreleased] + last 3 versions + newest remediation plan.

   Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

1. Do NOT push unless the user asked. Leave the branch local.

Why archive instead of a manifest or renamed-in-place

• Anchor integrity: backlog rows cite review-inbox/… paths. A move + per-batch subdirectory keeps those paths resolvable (and git log --follow preserves history).
• Next-batch cleanliness: Phase 0's staging-then-triage flow only reads the flat review-inbox/. By the time the next batch stages, the flat dir is empty and the extractor subagent reads only the NEW files — no need for the extractor to filter against a manifest or frontmatter stamp.
• Context savings: the extractor subagent's directory scan ignores archive/ by default (no recursion). Skipping thousands of already-processed lines per batch.

Phase 6.5 — Publish accepted rows to GitHub Issues (when --publish is set)

Skip this phase if --publish is not set.

For every row successfully materialized through backlog.mjs in this batch (Phase 4's deduped + split set, after Phase 6 completes), file a public GitHub Issue against darylmcd/Roslyn-Backed-MCP using the shared renderer. This validates the schema + issue template by exercising it on every accepted finding — the user's load-bearing reason for hooking publish into intake rather than a separate skill.

1. Preconditions. gh is on PATH AND gh auth status reports authenticated. If either fails, emit one warning line per row (gh unavailable — printed body to stdout instead) and fall back to print-only for the whole phase. Do not raise.
2. Dot-source the renderer.

   pwsh -NoProfile -Command ". '${CLAUDE_PLUGIN_ROOT}/skills/mcp-server-surface-test/lib/render-finding.ps1'; <render-and-file logic>"

The renderer is the source of truth. Do NOT hand-roll a body — drift between the consumer auto-file path and the maintainer publish path is the failure mode this Row 2 design exists to prevent.

1. Per-row loop. For each accepted row:

• Construct a finding hashtable from the row's fields (id, source_repo, severity, area, server_version, anchors, finding, repro, proposed_fix). The source_audit field is the basename of the prose audit report this row was extracted from (or the empty string when the row was created from a sweep retro instead of an audit).
• Call Test-FindingShouldRefusePublicFile -Finding $f. If $true, do not call `gh`. Print the rendered Issue body to stdout with the SECURITY/P0 escalation banner already prepended by Render-FindingIssue. Add (refused — pre-disclosure safeguard) to the row's audit-trail entry in the final summary.
• Dedup pre-check (load-bearing). Before filing, query the issue tracker for a prior filing of the same row. The shared renderer's bodies always include a Closes <row-id> in ai_docs/backlog.md line, so the row id is the canonical fingerprint:

     gh issue list --repo darylmcd/Roslyn-Backed-MCP \
       --state all \
       --search "Closes ${rowId} in ai_docs/backlog.md in:body" \
       --json number,state,title --limit 5

Apply these rules in order:

• Open hit: skip filing. Capture the existing Issue URL and use it (instead of a freshly-filed one) when annotating the backlog row's do cell. Emit → skipped: already tracked as #<N> (open) in the audit trail.
• Closed hit: skip filing. Emit → skipped: previously resolved as #<N> (closed). Do not refile or reuse the URL — closed issues with the same row id imply a prior fix that's now regressing, and the operator should re-open manually if appropriate.
• No hit: proceed to Render-FindingIssue + gh issue create. As a belt-and-braces secondary check, also do a title-keyword search (<primary tool name> in:title) and skip with a warning if a strong title near-match is found on an open issue (covers the rare case where a sibling skill auto-filed before backlog-intake ran). The row-id check is the primary gate; this is the fallback for cross-skill collisions.
• Otherwise call Render-FindingIssue -Finding $f to get {title, labels, body, refusedPublic}. Write body to a tempfile, then:

     gh issue create --repo darylmcd/Roslyn-Backed-MCP \
       --title "<title>" \
       --label "area:<area>" --label "severity:<severity>" \
       --body-file <tempfile>

• Capture the returned Issue URL (or the deduped existing URL from the pre-check) and use backlog.mjs update --do-file to replace the complete slim do cell so the planner can cite the public Issue (Closes #N) when the row is sized into an initiative. Do not edit the table directly.

1. Recommit when rows changed. If any row gained an Issue URL, the working tree now diverges from Phase 6's commit. Amend the Phase 6 commit OR add a follow-up commit on the same branch — your call which is cleaner. Do NOT push without explicit user confirmation.
2. Report counts in Phase 7. Add a Published line: Published: {filed} GitHub Issues + {refused} P0/security refused (printed only).

The two auto-file destinations (this skill and /mcp-server-surface-test --auto-file) MUST emit byte-identical bodies. The shared renderer is the contract; the renderer's tests at tests/RoslynMcp.Tests/Skills/RenderFindingScriptTests.cs enforce determinism.

Phase 7 — Report

Emit a final summary:

Backlog intake complete.
  Staged: {N} files from {M} repos (review-inbox/)
  Extracted: {raw} candidate items
  Deduped: {deduped} rows ({ratio}:1 dedupe)
  Dropped (already shipped): {shipped-count}
  Anchor fixes applied: {anchor-fix-count}
  Heroic splits: {split-count} rows → {split-total}
  Final: {output from `node ~/.claude/scripts/backlog.mjs count <repo-root>`}
  Commit: {SHA} on branch {branch-name} (local-only; push when ready)

Refusal cases (explicit)

• `review-inbox/` empty AND staging found nothing → refuse per Phase 0.
• Working tree dirty beyond the intake-owned backlog pair + review-inbox/ → refuse per Precondition 3.
• `backlog.md` shape unexpected → refuse per Precondition 5.
• Subagent returns 0 rows → do NOT write an empty commit. Report "no actionable items extracted from {N} files" and exit.
• Subagent returns > 60 rows after dedupe → stop and ask the user whether to proceed with a clearly-under-deduped result, rather than silently writing a heroic backlog.

Why a subagent for Phase 1

Each review file is 200-800 lines; a 14-file batch is 6000+ lines. Reading them all in-context would consume 30-50K tokens before any judgment work starts. The extraction subagent returns a compact structured list (typically 1-2K tokens), leaving the main agent's context free for the anchor-verify / heroic-split / commit phases, which require reading this repo's source files.

If the batch is small (≤3 files, ≤1000 total lines), skip the subagent and read directly — the overhead isn't worth it.

Distinct from related skills

• `close-backlog-rows`: removes specific row ids from the open table after their PRs ship. This skill (backlog-intake) ADDS rows from raw audit evidence. Use close-backlog-rows after a ship, this one after an audit wave.
• `reconcile-backlog-sweep-plan`: legacy-named compatibility skill that updates a remediation plan's state.json when its PRs have merged. Different file, different concern.
• `draft-changelog-entry`: drafts one changelog fragment per PR from commit metadata. Different artifact.
• `/backlog-remediate`: consumes the backlog this skill produces. Run backlog-intake first, then remediation.

Historical note

This skill replaces five PowerShell scripts that were deleted when it shipped: compare-external-audit-sources.ps1, import-deep-review-audit.ps1, new-deep-review-batch.ps1, new-deep-review-rollup.ps1, sync-deep-review-backlog.ps1. The last (the "sync" script) was the lossiest — it did literal-text dedupe via PowerShell regex and couldn't verify anchors, dedupe semantically, cross-check against CHANGELOG, or size rows to Rule 1/3/4. The only piece worth keeping from the pipeline was file staging, which is now a 150-line eng/stage-review-inbox.ps1.