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.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- gatesSkill
- verify-ticket-premiseSkill
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
- Distinctive: line 37
Never start with the expensive step.
- Very specific: line 41
Write every open ticket to a ledger file with disposition: null.
- Distinctive: line 50
every backticked symbol, table, column, config key, CLI flag
- Distinctive: line 51
every numeric claim (counts, ratios, row totals, versions)
- Distinctive: line 89
Only the third is a stale edge.
- Distinctive: line 115
Only for tickets whose gate is not ours to control.
≈ “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.
Files
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:
- 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 viewrefuted it. - Blocker edges.
blockedByis 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. - 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 aboveNever 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:NNNcoordinate - every backticked symbol, table, column, config key, CLI flag
- every numeric claim (counts, ratios, row totals, versions)
blockedBy/blocksedges- 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 itPROSE-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:
| grammar | example | verdict |
| 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 librarythendocs) - 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
| verdict | meaning | action |
CLOSE-SHIPPED | the capability exists and is reachable | close, cite file:line |
CLOSE-DECIDED | a decision note already answered it | close, cite the note |
CLOSE-FALSE | premise refuted | close, record the refutation |
RESCOPE | part shipped, remainder real | correct the body, keep open |
UNBLOCK | blocker edge stale | drop the edge, note it is startable |
GATED-CONFIRMED | external gate re-verified shut | record check + date |
GATED-OPEN | gate has opened | promote |
FIX-NOW | small defect exposed while verifying | fix in-process |
KEEP | premise holds, correctly open | leave |
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 -Nlimit is a truncation.wc -lfirst. - A comment citing a ticket is not independent evidence for that ticket. One source, twice.
- Prefer closing to implementing.
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
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.

