nwave-wave-summary

Files (31)

• SKILL.md
• why-these-rules.md · references/
• expected.md · self-test/01-the-largest-artifact/
• manifest.json · self-test/01-the-largest-artifact/
• expected.md · self-test/02-nothing-recorded/
• manifest.json · self-test/02-nothing-recorded/
• expected.md · self-test/03-no-target-given/
• manifest.json · self-test/03-no-target-given/
• expected.md · self-test/04-handles-everywhere/
• manifest.json · self-test/04-handles-everywhere/
• expected.md · self-test/05-tied-targets/
• manifest.json · self-test/05-tied-targets/
• expected.md · self-test/06-named-not-stated/
• manifest.json · self-test/06-named-not-stated/
• expected.md · self-test/07-named-target-missing/
• manifest.json · self-test/07-named-target-missing/
• expected.md · self-test/08-landed-differs-from-brief/
• manifest.json · self-test/08-landed-differs-from-brief/
• expected.md · self-test/09-attribution-incomplete/
• manifest.json · self-test/09-attribution-incomplete/
• expected.md · self-test/10-brief-and-outcome-agree/
• manifest.json · self-test/10-brief-and-outcome-agree/
• expected.md · self-test/11-nothing-the-brief-does-not-say/
• manifest.json · self-test/11-nothing-the-brief-does-not-say/
• expected.md · self-test/12-the-longest-brief/
• manifest.json · self-test/12-the-longest-brief/
• expected.md · self-test/13-promised-but-not-landed/
• manifest.json · self-test/13-promised-but-not-landed/
• expected.md · self-test/14-slice-number-not-found/
• manifest.json · self-test/14-slice-number-not-found/
• README.md · self-test/

SKILL.md (first lines)

# Wave summary — what the thinking decided, not where the work stands

A finished artifact is written for the wave that produced it: thousands of words whose load-bearing
sentences are keyed on identifiers the reader must resolve first (measurements in
`references/why-these-rules.md`). **A record nobody opens is not meaningfully different from one nobody
wrote.**

## What this answers, and what it does not

| Question | Command |
|---|---|
| What did this stage decide? | **this one** |
| Where does the work stand? | `phil:nwave-slice-status` |
| What was *I* doing? | `phil:resume` |
| What is on the board? | `phil:board-snapshot` |
| What is wrong with the cards? | `phil:groom-issues` |

**Never derive a status.** `phil:nwave-slice-status` owns every derivation over these files, and two
derivations over one source drift. Where the reader wants position, name that skill and stop.

## Resolving the target

**With a name, read `docs/feature/<name>/feature-delta.md`.**

**With no name, take the most recently touched feature** — and say that is what was taken:

```sh
git log -1 --format=%cI -- docs/feature/<id>/
```

**"Most recently completed" is not recorded anywhere, so it is not what this resolves.** No artifact
carries a completion marker; the newest commit touching a feature directory is the closest honest
signal, and it is not the same thing. A feature whose DISCUSS landed an hour ago sorts above one finished
last week — which is usually right and is sometimes not. **Name the feature and its artifact's date in
the output** so a wrong pick is visible immediately rather than inferred from a summary that reads
plausibly.

**Where two features tie, say so and stop.** Do not pick. Where no `docs/feature/` exists at all, or a
named feature does not, that is a different answer — see *Decision outcomes*.

## The summary

**200 words or fewer, counted over the whole rendered output** — the summary, the provenance line, the
outcome names, and any `ARGUMENT-DROPPED` or `ATTRIBUTION-INCOMPLETE` clause. Everything printed counts; a line outside the budget is
the budget leaking.

**Nothing counts it at run time**, and that is a deliberate trade rather than an oversight — see
*Half enforced, half promised* below.

**State what was decided and what it rules out.** A stage's value to a later reader is the decisions and
their boundaries — not the argument that produced them, which is what the artifact is for.

**Where the summary will not fit, cut the argument and never the decisions.** A decision named without
its reasoning is still useful; reasoning without its decision is not. Say what was left out, and report
`ARGUMENT-DROPPED`.

**Name the feature read, and the date of the artifact** — *"the board-snapshot feature record, last
changed 2026-09-08"*. The discarded 98% is then one command away and never has to be reconstructed from
the summary.

**Name the feature, never the path.** A path is a file-path identifier and the vocabulary rule below
forbids one everywhere, this line included — there is no exemption, because a reader who knows the
feature can find its record and a reader who cannot is not helped by a path either.

### State the decision, never its number

**No identifier of any kind reaches the output** — no file path, no bracketed identifier, no bare handle
like `D11` or `ADR-013`, and **no card number either**.

**This is the strictest vocabulary rule in the plugin, and the reason is positional.** A board read
prints `#34` because the number has a column of its own; forbidding it there would only launder it into
*card 34*. **A summary has no column.** Every identifier in it sits mid-sentence, where it is precisely
the lookup this command exists to spare the reader.

**A slice's own number is the one exemption, and nothing else gained one.** A slice summary must say
which slice it read, exactly as the stage summary names its feature — an identifier naming *what this
output is about* is not the lookup the rule exists to remove. Commit shas stay forbidden: a sha points
into history and is never the subject of a sentence.

So *"per the fourth locked decision"* is not the fix, and neither is *"as recorded in the delta"*. The fix
is to **say the thing**: *"the board's order is consumed and never recomputed, because a second producer
would make neither answer trustworthy."*

**Half enforced, half promised, and which is which matters — including inside the enforced half.**
`scripts/plain_language.py` holds both the counter and the forbidden list. **The fixtures apply the
forbidden list and do not apply the counter**: no fixture here can fail because something was too long,
and the counter appears in the suite only to prove a counterexample is *short* enough to fail for the
right reason. So the word ceiling is prose at run time and prose at build time; only the vocabulary is
checked.

Nothing counts the rendered output at run time either: this command holds no interpreter, deliberately,
because that is what keeps the read-only grant narrow. At run time both rules are this section.

### When the stage recorded nothing

**Say so. Do not summarise.** An absent or empty artifact, or one that records only a heading, gets
`NOTHING-RECORDED` and one sentence naming what was looked for and what was found.

A confident 200 words about a stage that decided nothing is the worst output this command can produce,
because it is indistinguishable afterwards from a real summary — and it is the failure this feature would
otherwise introduce, having never existed before.

## The slice mode — `--slice`

The stage summary reads one artifact. **The slice summary reads a brief and reconciles it against what
shipped**, because a brief states what a slice *intended* and the useful question is what it *landed*.

**200 words per slice**, same vocabulary rule.

**Resolve the feature first** — by name, or as the stage mode resolves its default — because slice
numbers repeat across features: a slice number names a brief inside that feature. **With a number, read
that slice. With none, read the feature's most recently touched brief**, named in the output for the same
reason. **Never summarise every slice
at once:** a per-slice bound leaves the whole output unbounded, on a command whose one promise is a
bounded read. Where briefs tie, that is `TARGET-AMBIGUOUS`; where a number names no brief,
`TARGET-NOT-FOUND`.

### Attributing commits to a slice

From pmvanev/phil-claude-plugin, MIT.

More from pmvanev/phil-claude-plugin