differential-feature-refactor

Files (2)

• SKILL.md
• differential-template.md · references/

SKILL.md (first lines)

# Differential Feature Refactor

Produce a **differential document** — a side-by-side of *what we have* versus *what we will
have* — that a human annotates, and that then becomes the input to a refactor specification
and an implementation plan.

**Why this exists.** A ratified architecture — an interface with an ADR behind it — was
reimplemented in parallel 36 minutes after it landed, with no ADR of its own. Five days later the
original read as "dead code" and was nearly deleted, which would have destroyed both a live
integration path and a requirement-level extension point. Twenty-plus documents described that
architecture and at least one described it falsely. Nobody could tell design intent from
accumulated cruft. This skill makes the difference legible **before** someone acts on it.

## The one rule that matters

**Never infer design intent from code shape.**

Requirements (`FR-`/`NFR-`), ADRs, and recorded rulings are the *only* authority on intent.
Code is evidence of what was built, never of what was meant. Review docs and plans are
proposals, not authority.

Establish the authority set **before** reading any implementation. If a thing in the tree has
no authorising decision, that is an undefined point for the human — not a finding you resolve.

### Rationalizations — all of these mean STOP

| Rationalization | Reality |
|---|---|
| "No callers, so it's dead code." | No callers is evidence about wiring, not intent. That exact reading nearly deleted a ratified extension point. Name the decision that authorised it before you call anything dead. |
| "The newer implementation is obviously the intended one." | Recency is not authority. Two parallel implementations mean an *unrecorded* decision — an undefined point, not a finding. |
| "The improvement plan says the target is X." | A plan is a proposal. Only an ADR, a requirement, or a ruling authorises a target state. Otherwise mark it `[UNVERIFIED]` and raise a UP. |
| "Twenty docs describe this; I'll synthesise them." | At least one of them is false. Docs give candidate *intent*; the tree gives *current state*. Never the reverse. |
| "I cited `09-improvement-plan.md`, that's grounded." | A citation to another document is not a citation to the tree. Current-state claims need `path:line`. |
| "The open questions read better collected at the end." | They get skimmed and lost there. Each one lives in the section it belongs to. The template has no Open Questions heading. |

## Workflow

1. **Authority set first.** Collect the ADRs, requirements, and rulings that govern this
   feature. Nothing else may justify a target state. Do this before opening the implementation.
2. **Ground current state in the tree.** Where the project has a code-graph MCP server, prefer it
   over grep — callers, callees, tests-for and impact radius are the questions this step asks, and
   a graph answers them structurally. Fall back to Read/Grep where there is none, or where the
   graph does not reach. Every current-state claim carries `path:line`; anything you could not
   verify is marked `[UNVERIFIED]` inline.
3. **Write the document** from `references/differential-template.md` to
   `<docs>/work/YYYY-MM-DD-<feature>-differential.md` — the dated-work-record directory of the
   canonical tree, with the docs root read from `.ai-badger/config.json`'s `docs.root` (default
   `docs/`). If `work/` does not exist, create it with a README first (`scaffold-documentation`
   does this); do not invent a directory beside it and do not fall back to a scratch path.
4. **Collect the rulings with a generated review form** — invoke `owner-gate-review`,
   one card per undefined point. The reviewer clicks a verdict and types notes; the result lands
   as a markdown file the agent watches for, so nothing is hand-edited and nothing is pasted.
   Then **stop**. Do not proceed, do not answer your own undefined points, do not start planning.
   *No browser available?* Fall back to the in-document `<answer>` blocks below.
5. **On feedback return:** read every answer in full — verdict *and* note, and on the fallback
   path the whole `<answer>` block. Nothing is open by the form path's `## Not answered` list or
   by a remaining `UNANSWERED` token on the fallback path; both must be resolved before you go
   further. Review the answers as answers — challenge contradictions on the spot ("in §3 you
   chose A, this answer implies B; which wins?"), and any answer that opens a new gap becomes a
   new UP block, sent back. Silent deferral is forbidden.
6. **Brainstorm what the feedback opened up.** Where the project has a brainstorming skill —
   `superpowers:brainstorming` if it is installed — use it, and its design doc is the
   **refactor specification**. Otherwise write that specification yourself in the same shape:
   one decision per open question, each with the options considered and the one chosen. The
   reconciled verdicts are its input either way.
7. **Plan it.** Where the project has a planning skill — `superpowers:writing-plans` if
   installed — hand the specification to it. Otherwise write the plan directly: numbered,
   bite-sized tasks, each naming the files it touches and the test that proves it. Both
   documents join the differential in `<docs>/work/`, dated the same way; do not create a new
   home for them.

**The differential document is the midpoint, not the finish.** The skill's terminal output is a
refactor specification plus an implementation plan. Reporting the document as the deliverable is
an incomplete run.

## Undefined-point block — fixed, greppable shape

Every undefined point sits **inside the section it belongs to**, and looks exactly like this. The
`<answer>` slot is the **fallback** collection path, for when no browser is available — the
default is the generated review form (step 4). The block shape itself is not optional either way:
it is what the form's cards are built from, one card per UP, ids matching.

```markdown
#### UP-3 — Which of the two ingest paths survives?

**Question:** One precise, answerable question. No compound questions.

| # | Proposition | Trade-off |
|---|-------------|-----------|
| A | ... | ... |
| B | ... | ... |
| C | ... | ... |

**Feedback:**
<answer question="3">
UNANSWERED
</answer>
```

- Heading matches `^#### UP-\d+ — `, numbered sequentially across the whole document.
- **Exactly three** propositions, lettered A/B/C, each with a stated trade-off. Not two. Not four.
- The answer slot is a **delimited block**, not a line. Humans write multi-line answers, follow-up
  questions and half-decisions; a single-line slot silently loses everything after the first
  newline. Learned the hard way: a first pass used a line-shaped slot, and a reader parsing only
  that line concluded six points were unanswered when every one had a written answer beneath it.
- `question="<n>"` repeats the UP number so a block is self-identifying even when moved.
- The human replaces the `UNANSWERED` token inside the block. It appears **nowhere else** in the
  document, so answered and unanswered are distinguishable by inspection.
- **Read the whole block, never just the marker line.** An answer may be a counter-question — that
  is a legitimate answer and means the point stays open until you resolve it.

Fallback-path checks (the form path reports its own counts and a `## Not answered` list):

The commands below use POSIX shell features and are intended for macOS/Linux. On another
platform, use equivalent finite commands that preserve the same checks.

```bash
D=docs/work/YYYY-MM-DD-<feature>-differential.md
grep -c '^#### UP-' "$D"                                       # total points

From Arasz/ai-badger, MIT.

More from Arasz/ai-badger