nwave-issue-board

Files (64)

• SKILL.md
• projection.md · references/
• story-cards.md · references/
• expected.md · self-test/01-publish-happy-path/
• manifest.json · self-test/01-publish-happy-path/
• expected.md · self-test/02-notes-column-survives/
• manifest.json · self-test/02-notes-column-survives/
• expected.md · self-test/03-unknown-published-as-unknown/
• manifest.json · self-test/03-unknown-published-as-unknown/
• expected.md · self-test/04-human-state-outranks-refresh/
• manifest.json · self-test/04-human-state-outranks-refresh/
• expected.md · self-test/05-no-markers-append/
• manifest.json · self-test/05-no-markers-append/
• expected.md · self-test/06-wave-swaps-not-accumulates/
• manifest.json · self-test/06-wave-swaps-not-accumulates/
• expected.md · self-test/07-no-rows-before-roadmap/
• manifest.json · self-test/07-no-rows-before-roadmap/
• expected.md · self-test/08-deferred-slice-is-a-row/
• manifest.json · self-test/08-deferred-slice-is-a-row/
• expected.md · self-test/09-generated-roster-no-subissues/
• manifest.json · self-test/09-generated-roster-no-subissues/
• expected.md · self-test/11-forge-never-writes-back/
• manifest.json · self-test/11-forge-never-writes-back/
• expected.md · self-test/12-owner-decides-status/
• manifest.json · self-test/12-owner-decides-status/
• expected.md · self-test/13-roster-order-follows-roadmap/
• manifest.json · self-test/13-roster-order-follows-roadmap/
• expected.md · self-test/14-guessed-order-says-so/
• manifest.json · self-test/14-guessed-order-says-so/
• expected.md · self-test/15-roster-not-checkboxes/
• manifest.json · self-test/15-roster-not-checkboxes/
• expected.md · self-test/16-routing-line-from-wave-label/
• manifest.json · self-test/16-routing-line-from-wave-label/
• expected.md · self-test/17-projection-bounded-to-current-slice/
• manifest.json · self-test/17-projection-bounded-to-current-slice/
• expected.md · self-test/18-unknown-state-writes-no-column/
• manifest.json · self-test/18-unknown-state-writes-no-column/
• expected.md · self-test/19-block-has-one-writer/
• manifest.json · self-test/19-block-has-one-writer/
• expected.md · self-test/20-story-block-four-features/
• manifest.json · self-test/20-story-block-four-features/
• expected.md · self-test/21-feature-tier-block-unchanged/
• manifest.json · self-test/21-feature-tier-block-unchanged/
• expected.md · self-test/22-indented-tree-refused/
• manifest.json · self-test/22-indented-tree-refused/
• expected.md · self-test/23-feature-state-without-glyph-fails/
• manifest.json · self-test/23-feature-state-without-glyph-fails/
• expected.md · self-test/24-contested-current-feature-not-resolved/
• manifest.json · self-test/24-contested-current-feature-not-resolved/
• expected.md · self-test/25-three-waves-one-label/
• manifest.json · self-test/25-three-waves-one-label/
• expected.md · self-test/26-backwards-step-is-correct/
• manifest.json · self-test/26-backwards-step-is-correct/
• expected.md · self-test/27-story-no-routing-row/
• manifest.json · self-test/27-story-no-routing-row/
• expected.md · self-test/28-two-in-flight-both-visible/
• manifest.json · self-test/28-two-in-flight-both-visible/
• expected.md · self-test/29-current-feature-not-first-in-flight/
• manifest.json · self-test/29-current-feature-not-first-in-flight/
• expected.md · self-test/30-composed-description-under-standard/
• …and 4 more

SKILL.md (first lines)

# nWave Features on a Forge Board

nWave keeps the truth on disk and renders it locally. This skill maps those artifacts onto forge
objects so other people can see them. It adds **only the mapping and the publishing discipline** —
two things it deliberately does not own:

- **REQUIRED BACKGROUND: `phil:issue-board`** — every forge mechanic. Naming the target with `-R`,
  tier gating, label swaps versus board lists, Projects v2 being a separate API, sub-issue and
  dependency-link commands, absolute URLs, two-pass seeding, reading back the end state. Do not
  guess any of it from here; read it there.
- **REQUIRED BACKGROUND: `phil:nwave-slice-status`** — how to read a feature's artifacts and derive
  a status. It owns the vocabulary, the precedence between sources, and the cases where the honest
  answer is `unknown`.

**Ask `nwave-slice-status` for every status and publish what it returns; derive none here.** Two
derivations over the same files drift apart.

**This direction is one-way.** The forge is a projection of the artifacts. Nothing read from an
issue is ever written back into `docs/feature/`.

## The mapping

| nWave artifact | Forge object |
|---|---|
| Story — several features declaring one slug | **One issue**, where any feature declares membership. The card that moves. |
| Feature — `docs/feature/<id>/` | **One issue** where it declares no story; **a row in the story's feature roster** where it does. Carries the wave either way. |
| Slice — `slices/slice-NN-*.md`, or roadmap phase `NN` | A row in the feature's generated roster. Never its own issue. |
| Step — `roadmap.json` step `NN-MM` | A row in the feature's step table, **for the current slice only**. Never its own issue. |

**The feature is the card because the feature is what somebody owns.** A slice is never assignable to
a second developer, so slice cards crowd a shared board with items only the feature's owner can pick up,
while the board fails to say what a teammate needs: which features are in flight, and who has them.

**A board may already carry slice cards from the retired mapping; consolidating them is grooming, not
this skill.** Use `phil:groom-set`, under *Consolidate a decomposed feature*; a consolidation done wrong
closes real cards.

**A slice is never its own issue under this mapping, with no exception.** Two people working one feature
at once is `phil:issue-board`'s case under *Choosing what becomes an issue*, and a repo that needs it has
left this mapping. Every rule below — no rollup, no per-slice position, no sub-issue — assumes no slice
cards exist.

**On a story card, read `references/story-cards.md` whole before writing anything to it.** It holds
the story tier's wave rule, feature order, block layout and routing. Every rule here applies to a story
card too, except where that file names a story-tier exception.

Steps and slices stay rows because a 22-phase feature would otherwise mint hundreds of issues. The step
table is scoped to the current slice because every step of every slice in one description is
unreadable too.

`roadmap.json` supplies **ids and order** — of the steps inside a slice, and of the slices themselves.
A per-step `status` field in it is a status source `nwave-slice-status` already handles; take whatever it
returns.

## The roster is generated, and it is the same instrument as the step table

Slices are not issues, so **no sub-issue relationship is created for them and no forge rollup applies.**
Both forges' parent-completion mechanisms — GitHub's `subIssuesSummary`, GitLab's
`taskCompletionStatus` — count children this mapping no longer creates. `phil:issue-board` still owns
what they measure; nothing here reads them.

**Nothing computes the roster, so this skill generates it** — delimited and timestamped, the same
instrument as the step table. Both forges are identical on the roster: no epics, no second seeding pass.

**The tier still matters elsewhere.** Scoped labels, which the wave label uses, and real dependency
links are both Premium-gated, per `phil:issue-board`.

**Write the roster as plain rows with generated glyphs, never as `- [ ] ` checkboxes**, on either forge.
Both forges count checkboxes, so the temptation is real; but a checkbox is ticked by hand while work
completes on its own, and the card then shows the checkboxes' state rather than the work's.

**Per-row status is a glyph, generated from what `phil:nwave-slice-status` returns and never typed.** That
skill owns the vocabulary and defines **seven** values; this table is a rendering of them and nothing more:

| Its status | Glyph |
|---|---|
| `done` | `✓` |
| `current` | `▶` |
| `next` | `→` |
| `not started` | `·` |
| `blocked` | `!` |
| `deferred` | `⊘` |
| `unknown` | `?` |

**The feature roster renders a DIFFERENT vocabulary, and conflating them is a defect.** Slice rows carry
the seven step statuses above; feature rows carry the **six** values `phil:nwave-slice-status` folds —
there is no `next` at feature level, and `current` is `in progress`:

| Feature state | Glyph |
|---|---|
| `done` | `✓` |
| `in progress` | `▶` |
| `to do` | `·` |
| `blocked` | `!` |
| `deferred` | `⊘` |
| `unknown` | `?` |

**Two glyphs are reused, not one.** `▶` is `current` at slice level and `in progress` at feature level;
`·` is `not started` at slice level and `to do` at feature level. Both are safe only because the
vocabularies never share a table and every row prints its state word beside the glyph.

**Every value the owner can return has a glyph; a value with none fails loudly.** Degrading it to `·`
publishes unknown as not started, for a whole feature. A value added to the owner's vocabulary needs a
glyph added here. Invent no glyph for a value the owner does not define, and never omit a row to avoid
rendering its value.

**Every roster row carries a two-line description of what that slice does** — not just its name. A
reader inheriting the feature needs to know what the slice achieves without opening its brief; with
those descriptions, a reader named a card's wave and position inside thirty seconds (2026-08-14).

**Summarise what you link.** Give each linked artifact — the delta, the slice briefs, the journey — a
clause saying what it holds. Six bare URLs consume the whole thirty-second read.

### Compose the block's own sentences against the clarity standard

**Compose against `${CLAUDE_PLUGIN_ROOT}/rules/writing.md` as you write; run no editor pass afterwards.**
`phil:eos` applies the same principles when a human invokes it, and is not a stage here: a pass over the
block is a second writer.

From pmvanev/phil-claude-plugin, MIT.

More from pmvanev/phil-claude-plugin