khosra/.claude/skills/feature-loop/SKILL.md

# The feature loop

Seven steps, in order: **Clarify → Plan → Implement → Verify → Document → Commit → Report.**
`CLAUDE.md` holds the rules; this file holds the procedure.

Scale, do not skip. A one-sentence request gets one line of plan and a short report — and still gets
the conflict check, propagation, verification, the `state.md` touch and the stale-reference sweep.
Casual phrasing is not a smaller change: *"default-language files do not need the `.en` part"* is one
unambiguous sentence that rewrites filenames on disk, makes a suffix optional in code, and falsifies
every doc calling it required.

## Propagation — a change is not done until every surface agrees

One request can touch four surfaces. Name each as done or n/a before reporting; the ones people miss
are the first and the last.

| Surface | What it means |
|---|---|
| the site root | Out of reach: it lives in its own repo (ADR-0011). A disk-contract change ships a **written migration step** the author runs, plus a note on whether any bundle key or URL moves. Never claim to have migrated files you cannot see. |
| code | The engine, plus a test for the new behaviour. |
| the theme | Out of reach, like the site root (ADR-0023). This repo ships a **contract extension** in
`harness/theme-contract.md` plus a written note of what a theme must do — never the theme itself, and never
a layout or markup decision dressed as an engine feature. |
| fixtures and emitted output | Fixture sites in `testdata/`, the embedded default templates (a reference implementation of the contract), and anything reading a field or path shape you altered. |
| harness docs | Every doc, ADR, marker or example that assumes the old form. An ADR that mandates what you just made optional is not stale, it is **contradicted** — supersede it, do not quietly reword it. |

---

## 1. Clarify

Read `harness/state.md`, then `harness/README.md` — the map, always, before deciding what else to open.

**A handoff is not evidence.** If `.scratch/continue.md` says something is pending, waiting, or unfinished,
run `git log --oneline -- <the path it names>` before planning from it. The file is uncommitted, so no gate
compares it to anything, and it is written *during* a change whose commit can still move underneath it. The
log is the only record of what landed. Offering the human work that is already in `HEAD` wastes the turn
they asked the question in.
For code, read the compressed form before the source: `harness/surface.md` locates every declaration,
`go doc` gives a package's surface, a test states its contract. Disciplines: `harness/context-economy.md`.
Use its topic-ownership table to list the docs owning anything this change asserts a rule about,
and read those. That list is a floor: skipping it is how a rule gets written twice and the second
copy contradicts the first.

### Conflict check — every request

Before anything else, ask whether the request contradicts something already decided. Classify and
act; do not average two positions into a compromise nobody chose.

| Kind | Examples | What to do |
|---|---|---|
| **Hard** — reverses a deliberate decision | an ADR, an architecture invariant, the permalink shape, the untrusted boundary, a `_MAX` budget, a frozen contract, the dependency policy | **Stop.** Quote the line, name the file, give both paths: comply, or change the decision (new ADR, or supersede the old one). Wait. Never pick for them. |
| **Soft** — exceeds a convention | a `_WARN` threshold, a style-floor preference, a latent item's trigger, a shape sketched in `ideas/` | State it in one line, proceed with the request, record the deviation where the convention lives. Conventions are a floor, not a decision. |
| **Stale** — a doc contradicts the code | `state.md` inventory, a STATUS line, an out-of-date example | Auto-resolve: the code wins. Fix the doc in Document, mention it in the report. No question needed. |
| **None** — the request refines or extends what is written | asking for more of something a doc already describes as built | Proceed. Say nothing about it. |

Resolve intelligently where the answer is genuinely unambiguous — a stale doc, or a request that is a
superset of what is written. Surface anything where a reasonable person could have meant either
thing, and everything in the Hard row without exception. One conflict is worth one message; a
silently reversed decision costs the trust in every other decision.

Then decide what you genuinely do not know. Ask **only** questions whose answer changes the code or
the bytes on disk — but ask every one of those. Batched, one message, up front, each with a **bold**
default so silence answers. **There is no cap** (`CLAUDE.md` §4): a request carrying six real forks gets
six questions, and splitting them across turns to look brisk wastes more of the human's time than asking
once. This file said "maximum three" until the cap was lifted in `CLAUDE.md` and not here.

Never ask about: anything `conventions.md`, `content-model.md`, or an ADR already decides; naming,
formatting, file placement, test style; permission to follow the constitution; "would you like me
to also…" — that is scope creep wearing a question mark.

Do ask when: the feature has two plausible disk formats, URL shapes, or authoring ergonomics; it
touches an open question in `state.md`; success criteria are not observable from the request;
it appears to need a dependency, a new package, or a frozen-contract change.

No such questions? One line — *"No questions — assuming tag pages live at the section root and
reuse the post list template."* — and continue.

## 2. Plan

Post this before writing code. Under fifteen lines.

```
Goal:              one sentence, observable from outside the program
Reduces to:        Bundle | Stage | Query | View | Interaction | Effect | bundle-as-program
Success criteria:  the checks that will prove it works (commands, URLs, expected output)
Files:             exact paths, marked new / edit, with an estimated ±LOC each
New deps:          none  (anything else needs an ADR first — stop and ask)
Earn-it check:     which counter this increments, and whether an extraction is due this change
Trust check:       does any untrusted input reach this code? ("n/a" if not)
Docs read:         the owning docs you opened ("none" only if the change asserts no rules)
Not doing:         the two or three adjacent temptations you are declining
```

Wait for a go-ahead unless the user said "just do it" or the change is under ten lines in one file.
If the plan reveals a trunk, say so instead of planning and offer the leaf.

## 3. Implement

- Smallest code satisfying the success criteria. Nothing for the version after next.
- Only the planned files. No renames, reordering, reformatting beyond `gofmt`, or tidying of
  neighbouring code.
- Something wrong outside the plan? One line on the Latent list in `harness/state.md`, keep moving.
  That is the whole mechanism; use it instead of a drive-by fix.
- Reuse the existing shape before inventing one. Copying eight lines twice beats an abstraction at
  use two; the third use is when it becomes a design.
- Halt and ask if any `CLAUDE.md §6` stop condition fires. Halting costs one message.

## 4. Verify

Run `./scripts/verify.sh --quiet` — doc coupling, format, vet, build, test, dependency allowlist,
budgets. Quiet prints only failures, warnings and the verdict; use the loud form when a gate fails and
you want its neighbours, or when auditing the gates themselves.

Then **at least one piece of feature-specific evidence you actually executed**: the new test name
and its output, `curl -s localhost:PORT/path | head`, a golden-file diff, the before/after fragment
of real generated markup, or benchmark numbers.

Budget failure: shrink the change, or stop and propose an ADR raising it. Never raise it silently.

**A standing advisory is a defect.** If a warning fires on correct code and will keep firing, either the
check is wrong or the code is — resolve which, in that change. Tolerated warnings are how the whole
channel stops being read, and the count creeping from one to two is the only signal you get.

Never write "should work", "this will now…", or your own diff summarised as a result. If you could
not run something, say which and why.

## 5. Document

Same change, not later. Triggers: `harness/README.md`. Walk the propagation table above — every surface
done or explicitly n/a. Minimum:

- `harness/state.md`: inventory rows, counters, latent items added/removed — in *this* commit, never a
  trailing one, which is what `verify.sh` compares (ADR-0057).
- `harness/decisions.md`: an ADR if the choice is expensive to reverse. Six lines. First open the doc
  that owns the topic — if it already carries the rule, amend it there; an ADR restating an
  existing doc is a duplicate, not a decision.
- Any other doc **only if the change made it wrong.** Never state one fact in two docs.

Doc edits are surgical too. Prefer deleting a stale line to appending a corrected one.

**Then sweep for what you replaced.** Any rule, value, name or path you changed may be described
elsewhere in the old terms:

```
grep -rn '<old form>' harness CLAUDE.md HARNESS.md ideas reference .claude scripts
```

`verify.sh` fails on dangling file paths, ADR numbers and `CLAUDE.md` section refs. It cannot detect
a sentence that is merely now untrue, or a concept renamed in one place — that sweep is the author's,
and skipping it is how a doc ends up contradicting the file it points at.

## 6. Commit

Not optional and not asked for: the work is committed before the report, every time. `CLAUDE.md` §4
holds the rule; this is how.

**The notice, if this session did not ask for automatic commits.** Before the first commit only, on
its own line, visible:

```
**Committing this to git** — and every later batch of changes in this session. Say "stop committing"
and I will leave the tree dirty instead.
```

Once said, it is not repeated. If the human asked for automatic commits — in this session or by
having put the rule here — skip the notice entirely; repeating a notice for something already agreed
is noise that trains them to skim the next one.

**What goes in one commit.** The changes that would be reverted together (`conventions.md` "Git").
Bundle freely inside one unit: code with its test, its `state.md` row and its ADR are one commit
because reverting the code without the doc leaves a lie. Split when a second pass is independently
revertible — a fix to something you noticed afterwards, or a doc correction that was already wrong
before this change. "Which of these would I want to undo alone?" answers it faster than any rule.

**How.**

- `git status` first: an unexpected file is a stop condition, not something to sweep into `git add -A`.
- Stage what the change touched, then check `git diff --cached --stat` against the plan's file list.
- The pre-commit hook runs `verify.sh`, so a red gate blocks the commit. That is the design — fix the
  gate or the code, do not reach for `--no-verify`.
- Subject imperative, under 72 characters. Body says *why*, plus the numbers the change earned
  (LOC, counters, a benchmark) since `git log` is the map when no agent is available.
- Never `git push`. Publishing is the human's; committing is bookkeeping.
- Scratch files, `ideas/`, `reference/` and anything under the scratchpad stay out.

**Then reconcile the handoff — once the commit exists, never before.** If `.scratch/continue.md` carried a
planned item this change completed, delete that item now and note anything learned that changes a later
one. Doing it during Document records the plan's version of events instead of the result: an amend, a
squash or a late fix moves the commit under a handoff that already claims what it contains.

## 7. Report

Short — one line each, no prose unless a conflict or a stop condition needs explaining. Drop the lines
that are genuinely n/a rather than padding them.

```
Did:        what now works, in the user's terms
Evidence:   the command you ran and its result
Diff:       files touched, ±LOC
Propagated: content / code / templates / docs — each done or n/a, with content files named
Committed:  the commit subjects this produced, one line each
Earned:     counters after this change; anything now due for extraction
Skipped:    what you deliberately did not do, and the latent items you logged
Conflicts:  hard ones surfaced and how they were settled, soft ones deviated from, or "none"
Swept:      the old form you grepped for after a rename, or "n/a"
```

---

## Failure modes to catch in yourself

| Symptom | What it means | Do instead |
|---|---|---|
| Interface with one implementation | Anticipating, not designing | Concrete type; wait for the second |
| A parameter no caller passes | Speculative flexibility | Delete it |
| Reaching for a dependency for something small | Usually 40 lines of stdlib | Write the 40 lines, or stop and ask |
| Hand-rolling something specified elsewhere | A bug farm whose test vectors you must also transcribe | Take the maintained module (ADR-0083), with its ADR |
| Wanting a `switch` on post type in the core | A View or Query is the seam | Move it out |
| Needing a mock to test | Wrong seam | `fstest.MapFS` or a `testdata` dir |
| Renaming "for clarity" mid-feature | Drive-by refactor | Latent list |
| Explaining why the boundary can bend here | It cannot (ADR-0003) | Stop and ask |
| Plan grew while implementing | Scope drift | Stop, re-plan, continue |
| Writing a rule without reading its owning doc | Guessing where you could look | `harness/README.md` topic table, then amend that doc |
| Quietly doing what was asked against a recorded decision | The conflict was real and you hid it | Quote the line, give both paths, wait |
| Changed the rule in code, left the docs describing the old one | Propagation stopped at the first surface | Walk all four surfaces |
| Made a field optional, left the ADR mandating it | Contradicted, not stale | Supersede the ADR |
| Treated a one-sentence request as a narrow change | Articulation size is not blast radius | Walk the propagation table |
| Splitting the difference between request and policy | A compromise nobody chose | Surface it; the human picks |
| Ending a turn with the work only in the working tree | The one copy is the one that gets lost | Commit before reporting |
| Offering work a handoff calls pending | The file states intent; only the log states what landed | `git log -- <path>` before trusting it |
| Ticking the handoff during Document | The commit can still move under it | Reconcile it after the commit exists |
| Opening a file to find out what is in it | The generated surface already answers it | `harness/surface.md`, then read the range |
| Grepping for callers before changing a signature | The compiler enumerates them exactly | Change it, then `go build ./...` |
| A shorter report that dropped a caveat, case or number | Truncation wearing compression's clothes | Restore it; cut words, never findings |
| One commit per file, or per doc touched | Shredding a single revertible unit | Bundle what would be undone together |
| Committing without ever saying you would | Consent assumed, not given | The notice, once, before the first one |