agentleFS
The-40-ThievesThe-40-Thieves/obsidian-tc/.claude/skills/reconcile-backlog/SKILL.md

reconcile-backlog

Skill13 starsChanged 5 days agoApache-2.0View on GitHub

Reconcile the whole open Linear backlog against HEAD, upstream state, and the decision record — a batch wrapper around verify-ticket-premise that adds external-gate checks, blocker-edge auditing, a disposition taxonomy, and an on-disk ledger so the pass survives compaction.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never start with the expensive step.

    line 37
  2. Very specific:

    Write every open ticket to a ledger file with disposition: null.

    line 41
  3. Distinctive:

    every backticked symbol, table, column, config key, CLI flag

    line 50
  4. Distinctive:

    every numeric claim (counts, ratios, row totals, versions)

    line 51
  5. Distinctive:

    Only the third is a stale edge.

    line 89
  6. Distinctive:

    Only for tickets whose gate is not ours to control.

    line 115

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

reconcile-backlog

verify-ticket-premise verifies one ticket before you implement it. This is the batch form: it reconciles the entire open backlog and decides what each ticket is, not whether to code it.

Three things it adds that the single-ticket skill does not cover:

  1. External gates. Many tickets here wait on third-party state — a package version, a spec revision, a model's availability. The premise skill only reads this repo, so an upstream gate that opened (or a claim that it opened) is invisible to it. On 2026-08-04 a reconciliation asserted sqlite-vec 0.1.10 had shipped; it had not, and one npm view refuted it.
  2. Blocker edges. blockedBy is the least reliable field on a ticket here. Blockers close without their dependents being revisited, so a "blocked" ticket is frequently startable. Note that most edges in this backlog are prose, not the field — see the grammar rule in Stage 2, which is what makes this stage work at all.
  3. An on-disk ledger. A 40+ ticket pass will outlive its context window. Verdicts written to disk as you go make the pass resumable and stop you re-deriving what you already proved.

The ordering rule

Cheapest disqualifier first. Most tickets are resolved without reading code:

blocker edge   ->  grep the body for a FORWARD-POINTER verb, then one API read on what it names
                   (state alone discriminates nothing — 31 of 34 cited tickets are already Done)
upstream gate  ->  one npm view / context7 / web check
already shipped ->  one grep for the CAPABILITY (not the ticket's identifier)
coordinates    ->  scripted file:line resolution
central claim  ->  the expensive one; only for what survives the above

Never start with the expensive step. Never start with the title.

Stage 0 — Ledger

Write every open ticket to a ledger file with disposition: null. Every stage appends. This is the artifact, not your context.

Stage 1 — Fetch and extract (mechanical)

get_issue with includeRelations: true. Read the whole body plus the newest correction banner — the banner usually supersedes the body below it. Write the body to disk, then extract:

  • every path/file.ts:NNN coordinate
  • every backticked symbol, table, column, config key, CLI flag
  • every numeric claim (counts, ratios, row totals, versions)
  • blockedBy / blocks edges
  • any third-party package, spec, or model name

Then drop the body from context. It is on disk.

Stage 2 — Mechanical verification (scripted, no judgement)

Per coordinate, resolve to EXACT / MOVED / GONE. A structural refactor silently invalidates every ticket citing the files it touched, and no gate catches it because tickets are not code — cli.ts went 1256 → 113 lines and five tickets still cited lines 381, 793, 855, 1300.

Resolve them with the parser, not with rg:

just where <Symbol>          # DECLARED / USED / PROSE-ONLY; exit 1 when nothing declares it

PROSE-ONLY is the bucket that decides absence claims. A backlog pass reads dozens of "X does not exist" assertions, and this repo's comments discuss deleted symbols by name. A grep that finds the obituary reports the corpse as alive.

Blocker edges: the state is not the finding — the GRAMMAR is

Reading the blocker's current state is necessary and nowhere near sufficient. Measured 2026-08-06 over the whole open backlog: 31 of the 34 tickets cited by open tickets are Done. A sweep that flags "cites a closed ticket" therefore flags almost everything and discriminates nothing.

Mature backlogs cite closed work constantly, and legitimately. Classify by how the sentence uses the reference:

grammarexampleverdict
historical attribution"the vault_id column on vault_edges was added later"correct — leave it
provenance"shipped in #675, cited in that release's CHANGELOG"correct — leave it
forward pointer"blocked on <ticket>", "pending <ticket>", "waits on someone taking X"defect once closed

Only the third is a stale edge. Grep for the verbs, not the ids:

rg -i 'blocked (on|by)|pending|waits? on|gated on|until .*THE-[0-9]|prerequisite' <body-on-disk>

Three instances of exactly this shipped undetected until 2026-08-06 — a closed ticket cited as live in the README (it had closed by de-scoping that very README), one ticket on another, and a third on both Two more such ids. Each rendered as a valid link, so nothing flagged them. A closed ticket cited as a forward pointer reads as "work someone will get to" when the truth is "nobody owns this" — and those need opposite decisions, which is why the distinction is worth a stage.

Status update (2026-09-30): The stale blockers found in docs/design/experiential-reflection.md lines 39-46 (four preference keys with unmet prerequisites) have been resolved: captureContent now defaults ON (turned OFF by securityProfile: "hardened"), transcript-capture prerequisite is resolved, and all four keys have evolved status: search_mode written but not yet read; output_format waiting on reader pattern; detail/citation_style are explicit call-time arguments; confirmation_level intentionally never learned (security floor, tracked via approval outcomes instead).

A caution when building the closed-set oracle: list_issues state=Done limit=N returns exactly N with hasNextPage: true, and unioning two orderings did not close it (250 -> 285, still paginated). So it is one-directional — presence proves Done; absence proves nothing. Never render a "not closed" verdict from it.

Stage 3 — External gates (context7 + web)

Only for tickets whose gate is not ours to control. Record the check and its date on the ticket, so the next pass re-checks rather than re-litigates.

  • package currency: npm view <pkg> dist-tags — an alpha is not a release
  • library/API semantics: context7 (npx ctx7@latest library then docs)
  • spec revisions, upstream issues, competitor claims: web search

Stage 4 — Judgement (per ticket, priority order)

Apply verify-ticket-premise steps 4–5 to what survived. Search by capability, not by the ticket's identifier — work often ships under a different name than the ticket asking for it.

Stage 5 — Disposition

verdictmeaningaction
CLOSE-SHIPPEDthe capability exists and is reachableclose, cite file:line
CLOSE-DECIDEDa decision note already answered itclose, cite the note
CLOSE-FALSEpremise refutedclose, record the refutation
RESCOPEpart shipped, remainder realcorrect the body, keep open
UNBLOCKblocker edge staledrop the edge, note it is startable
GATED-CONFIRMEDexternal gate re-verified shutrecord check + date
GATED-OPENgate has openedpromote
FIX-NOWsmall defect exposed while verifyingfix in-process
KEEPpremise holds, correctly openleave

Stage 6 — Act

Defects found while reconciling are fixed in process, not filed. Filing a ticket for a five-line fix converts work into inventory. Batch them into themed PRs with the reconciliation that found them.

Two limits on that rule, so it does not become a licence to balloon scope:

  • Record every in-process fix in the ledger and the writeup. Fixed-not-filed must never mean invisible.
  • If a fix is not small, or is risky, or changes a public surface, stop and surface it instead of absorbing it silently. "Fix it in process" is about not filing paperwork for trivia, not about making unreviewed judgement calls on real design.

Non-negotiables

  • Zero hits is a result you must state: 0 hits for `<exact pattern>` .
  • Never audit from a title. 6 of 6 findings false in one session, then 3 of 3 in another — all refuted by the ticket's own body.
  • A truncated listing is not an inventory. A result exactly as long as your head -N limit is a truncation. wc -l first.
  • A comment citing a ticket is not independent evidence for that ticket. One source, twice.
  • Prefer closing to implementing.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.