The-Artificer-of-Ciphers-LLC/skills-from-the-artificer / adr-phase-coverage
adr-phase-coverage
VerifiedUse when a user needs to turn a design doc, ADR, RFC, or spec into a phased implementation plan — or verify that an existing phase breakdown actually covers everything the design promised. The failure mode this catches: Phase N defers a deliverable to Phase N+1, Phase N+1 never claims it, and it ships as promised-but-not-built. Trigger when users say: 'break this into phases', 'turn this ADR/RFC into a roadmap', 'is my phase plan complete', 'what slips between phases', 'sanity check my phase breakdown', 'audit this epic for coverage gaps', or ask to sequence any architectural work into milestones. Also trigger on `/adr-phase-coverage`. Do NOT trigger for: authoring a new ADR, updating ADR rationale, writing a PRD, debugging a stuck deploy, or dependency analysis.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.7 KB |
| assets/trace.adr1244-broken.json | config | 2.0 KB |
| assets/trace.example.json | config | 2.4 KB |
| evals/evals.json | config | 3.0 KB |
| evals/fixtures/ROADMAP-apikeys.md | markdown | 893 B |
| evals/fixtures/adr-0007-apikeys.md | markdown | 1.1 KB |
| evals/trigger-eval.json | config | 3.7 KB |
| references/adapting-to-your-repo.md | markdown | 4.6 KB |
| references/anti-patterns.md | markdown | 5.5 KB |
| references/methodology.md | markdown | 5.4 KB |
| scripts/check_coverage.py | script | 11.2 KB |
references/anti-patterns.md
View on GitHub# Anti-pattern catalog
The decomposition failures this skill exists to catch, each with the smell, the check that catches
it, and the fix.
## Contents
- [1. The orphaned decision](#1-the-orphaned-decision)
- [2. The dangling deferral ("see Phase N+1") — the ADR-1244 bug](#2-the-dangling-deferral-see-phase-n1-the-adr-1244-bug)
- [3. The unwired keystone (lib-without-entry-point)](#3-the-unwired-keystone-lib-without-entry-point)
- [4. Multi-owner ambiguity](#4-multi-owner-ambiguity)
- [5. Docs describe what no phase builds](#5-docs-describe-what-no-phase-builds)
## 1. The orphaned decision
**Smell.** A decision in the ADR has no phase that claims it. Often invisible because the ADR's own
"implementation phases" list looks complete — but a decision *implies* a deliverable that nobody
scheduled.
**Catch.** `orphan-decision` — decision id appears in `decisions[]` but in no phase's `owns[]`.
**Fix.** Assign it to a phase and give that phase a concrete acceptance criterion for it.
## 2. The dangling deferral ("see Phase N+1") — the ADR-1244 bug
**Smell.** Phase N's notes say "the X piece lands in Phase M." Phase M's real scope turns out to be
something else; it never lists X. X is now owned by no one, but *everyone believes it's covered*
because Phase N "handed it off." Each phase passes its own review.
**Catch.** `dangling-deferral` — a phase's `defers: [{to: M, what: X}]` where phase M neither owns X
nor lists it in `accepts`.
**Fix.** Go to phase M and add X to its `owns`/`accepts` by the same id. A hand-off is only real when
the receiver acknowledges it.
### Case study: a real "capability ecosystem" ADR
A real project's ADR (a plugin/"capability" ecosystem: versioned manifests, a runtime registry, a
URL importer, a trust gate, and a user-facing `… capability install/update/remove/list` management
command) was decomposed into 6 phases. The specifics below are from that project, but the shape is
universal — substitute your own layers.
The ADR was decomposed into 6 phases:
| Phase | Scope |
|---|---|
| 1 | Versioned manifest (D1) |
| 2 | Registry overlay (D2) |
| 3 | Source resolver + ledger (D3, D4) |
| 4 | Trust gate + upgrade — **`installCapability`/`upgradeCapability`/`removeCapability` library** (D5, D6) |
| 5 | Registry-driven dispatch (D7) |
| 6 | Capability matrix + docs (D9) |
Phase 4 built the lifecycle **library** and its acceptance pointed downstream: "the user-facing
`gsd capability install/update/remove/list` command lands in Phase 5." But Phase 5's actual scope
(D7) was registry-driven dispatch of *capability-declared* command families — a different thing. So
the management command — the keystone the whole ecosystem exists to provide — was **nobody's
acceptance criterion across all six phases**, while the docs (`gsd-capability-command.md`, the
how-tos) described it as shipping.
It surfaced only during Phase 6 diátaxis verification (the first step whose job is to check a doc
claim against a real invocable command) — by luck, not design.
Run the checker on the as-shipped trace to see it caught deterministically:
```
$ python3 scripts/check_coverage.py assets/trace.adr1244-broken.json
🔴 orphan-decision — UX-manage is owned by NO phase.
🔴 dangling-deferral — Phase 4 defers 'UX-manage' to phase 5, but phase 5 neither owns nor accepts it.
```
The corrected decomposition (`assets/trace.example.json`) moves `UX-manage` into Phase 6's `owns`
with an acceptance criterion that names the wired command — and passes.
## 3. The unwired keystone (lib-without-entry-point)
**Smell.** A user-facing capability is technically "owned" — but the owning phase's acceptance is
"the library function exists and is tested." The function ships; no command/route/UI calls it; users
can't reach it. This is the horizontal-layering trap: the bottom layer is complete, the top is
stranded (see `methodology.md` §3).
**Catch.** `keystone-unwired` — a `user_facing: true` decision is owned, but no owning phase's
`accepts` names a user-reachable surface (the checker scans for command/route/UI/wired/"user can
invoke" language).
**Fix.** Add an acceptance criterion that names the surface and the wiring: "user can run `foo`,
dispatched to the Phase-K library." If you can't name a phase that wires it, you've found the gap —
schedule the owning work now. Follow up after that phase ships with a code-layer reachability check
(dead-code / unused-export tool) to prove the entry point stayed wired.
## 4. Multi-owner ambiguity
**Smell.** Two phases both list the same decision. Sometimes intentional (genuinely split work);
sometimes each phase quietly assumes the *other* one does the hard part.
**Catch.** `multi-owner` (warning) — a decision in 2+ phases' `owns[]`.
**Fix.** Confirm the split is deliberate and the phases' acceptance criteria carve the decision into
non-overlapping halves; otherwise consolidate to a single owner.
## 5. Docs describe what no phase builds
**Smell.** The reference docs / how-tos describe a command or behavior as shipping, but no phase owns
delivering it. Docs are written from the ADR's *intent*, so they race ahead of what the phases
actually schedule — and a confident doc masks a missing deliverable.
**Catch (process, not script).** During trace extraction (workflow step 2), treat the documentation
as a source of `user_facing` capabilities: if a doc says `gsd foo` exists, add `foo` as a
`user_facing` decision. It will then surface as `orphan-decision` or `keystone-unwired` if no phase
wires it. This is how a doc-vs-acceptance mismatch becomes a hard finding instead of a surprise.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |