fix(#1700): scope spike MANIFEST requirements per idea key (#3014)

* test(#1700): add failing-first regression test for spike MANIFEST.md idea scoping

Pins the deployed-text contract for spike.md's create_manifest step and
spike-wrap-up.md's gather/synthesize/write_skill steps before the fix lands,
so the fix commit demonstrates RED to GREEN.

* test(#1700): add issue ref to allow-test-rule exemption

lint-allow-test-rule-refs.cjs (ADR-456) requires a tracking-issue
reference on the same line as any new allow-test-rule: exemption.

* fix(#1700): scope spike MANIFEST.md Idea/Requirements per idea key

.planning/spikes/MANIFEST.md held one un-keyed ## Idea paragraph and one
flat ## Requirements list, while spike.md's own read path (load_prior_context
step d, frontier mode) assumed the tree holds several unrelated ideas across
campaigns. spike-wrap-up.md then copied that flat Requirements list verbatim
into every generated feature-area reference and the generated spike-findings
skill, so one idea's requirements leaked into another idea's build as
non-negotiable constraints.

Scopes both sides by an explicit idea key:
- spike.md's create_manifest step now writes MANIFEST.md as ## Ideas >
  ### {idea-key} subsections (idea paragraph + its own Requirements list),
  appends a new idea section instead of overwriting an existing one, and
  migrates a pre-fix flat-shape MANIFEST.md in place instead of discarding
  it. The ## Spikes table gains an Idea column. Spike README frontmatter
  carries the idea key.
- spike-wrap-up.md's gather/synthesize/write_skill steps resolve each
  spike's idea key and pull Requirements only from the idea key(s) actually
  represented among the spikes being wrapped.
- sketch.md's MANIFEST.md read (collateral of the same seam) is updated to
  match the new per-idea section shape.
- references/artifact-types.md no longer describes the project-level,
  durable-index MANIFEST.md as "(per-spike)".

Not a docs-vs-workflow conflict: docs/how-to/spike-and-sketch.md already
matches this contract ("all spikes are indexed in MANIFEST.md") and needed
no change; the defect was internal to spike.md (per-idea read assumption,
single-idea write template).

* test(#1700): make idea-frontmatter regex CRLF-safe

CONTRIBUTING.md's cross-platform portability rules (docs/contributing/
cross-platform-portability-rules.md) ban a bare \n literal matched against
fs.readFileSync'd content — Windows checkouts normalize to CRLF and would
silently break the assertion. Use \r?\n instead.

Found during self-review (code-review skill, Standards axis) before this
branch was handed off for verification.

* test(#1700): acknowledge emitted-size growth in spike.md, spike-wrap-up.md, sketch.md

The differential attribution check (tests/emitted-attribution.test.cjs,
ADR-2719) flagged unattributed byte growth in three emitted workflow files.
All three grew as a direct, necessary consequence of the #1700 fix (idea-key
scoping in spike.md's create_manifest, spike-wrap-up.md's gather/synthesize/
write_skill, and the matching one-line update to sketch.md's MANIFEST.md
read) — none of it is incidental prose. Growth stays well under the DEFAULT
tier byte cap (40960) for all three files; PRE_PHASE6 does not apply to
them (only plan-phase.md/execute-phase.md).

* chore(#1700): backfill changeset PR number to 3014

---------

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-02 22:31:23 -04:00
committed by GitHub
parent fd07e1a357
commit 1259e4b619
7 changed files with 308 additions and 25 deletions

View File

@@ -134,7 +134,7 @@ If spikes exist for this project, read them to ground the sketches in reality. M
**a.** Glob for `./.claude/skills/spike-findings-*/SKILL.md` and read any that exist, plus their `references/*.md`. These contain validated patterns and requirements.
**b.** Read `.planning/spikes/MANIFEST.md` if it exists — check the Requirements section for non-negotiable design constraints (e.g., "must support streaming", "must render markdown"). These requirements should be visible in the mockup even though the mockup doesn't implement them for real.
**b.** Read `.planning/spikes/MANIFEST.md` if it exists — it may hold separate `### {idea-key}` sections for several unrelated ideas. Check the Requirements list of the idea key relevant to this sketch's design direction (or all of them if none clearly matches) for non-negotiable design constraints (e.g., "must support streaming", "must render markdown"). These requirements should be visible in the mockup even though the mockup doesn't implement them for real.
**c.** Read `.planning/spikes/CONVENTIONS.md` if it exists — the established stack informs what's buildable and what interaction patterns are idiomatic.

View File

@@ -22,8 +22,12 @@ Read all files referenced by the invoking prompt's execution_context before star
<step name="gather">
## Gather Spike Inventory
1. Read `.planning/spikes/MANIFEST.md` for the overall idea context and requirements
2. Glob `.planning/spikes/*/README.md` and parse YAML frontmatter from each
1. Read `.planning/spikes/MANIFEST.md` for the `## Ideas` sections (each idea's paragraph and
its own scoped Requirements list) and the `## Spikes` table (its Idea column tells you which
idea key each spike row belongs to).
2. Glob `.planning/spikes/*/README.md` and parse YAML frontmatter from each — each spike's
`idea:` field is the idea key that owns it. If a README predates #1700 and has no `idea:`
field, resolve its idea key from the matching `## Spikes` table row's Idea column instead.
3. Check if `./.claude/skills/spike-findings-*/SKILL.md` exists for this project
- If yes: read its `processed_spikes` list from the metadata section and filter those out
- If no: all spikes are candidates
@@ -101,7 +105,12 @@ For each feature-area group, write a reference file at `references/[feature-area
## Requirements
[Non-negotiable design decisions from MANIFEST.md Requirements section that apply to this feature area. These MUST be honored in the real build. E.g., "Must use streaming JSON output", "Must support reconnection".]
[Non-negotiable design decisions pulled ONLY from the Requirements list of the idea key(s) that
own the spikes in this feature-area group — match each spike's `idea:` frontmatter (or Idea
column) to its `### {idea-key}` Requirements list in MANIFEST.md. These MUST be honored in the
real build. E.g., "Must use streaming JSON output", "Must support reconnection".
Never include a requirement from an idea key that has no spike in this group.]
## How to Build It
@@ -136,7 +145,8 @@ description: Implementation blueprint from spike experiments. Requirements, prov
<context>
## Project: [project-dir-name]
[One paragraph from MANIFEST.md describing the overall idea]
[One paragraph per idea key represented among the wrapped spikes, taken from that idea's
`### {idea-key}` section in MANIFEST.md — not the whole MANIFEST.md if it holds unrelated ideas.]
Spike sessions wrapped: [date(s)]
</context>
@@ -144,7 +154,11 @@ Spike sessions wrapped: [date(s)]
<requirements>
## Requirements
[Copied directly from MANIFEST.md Requirements section. These are non-negotiable design decisions that emerged from the user's choices during spiking. Every feature area reference must honor these.]
[Union of the Requirements lists for every idea key represented among the spikes being wrapped
in this session — never the whole MANIFEST.md. These are non-negotiable design decisions that
emerged from the user's choices while spiking those specific idea(s). Every feature area
reference must honor these. If this wrap-up spans more than one idea key, group the list by
idea key so a future reader can tell which requirement belongs to which idea.]
- [requirement 1]
- [requirement 2]
@@ -299,6 +313,7 @@ After the summary, present next-step options:
- [ ] Spikes grouped by feature area
- [ ] Spike-findings skill exists at `./.claude/skills/` with SKILL.md (including requirements), references/, sources/
- [ ] Reference files are implementation blueprints with Requirements, How to Build It, What to Avoid, Constraints
- [ ] Requirements in each reference file and in SKILL.md are scoped to the idea key(s) actually represented among the wrapped spikes — never blended with an unrelated idea's requirements
- [ ] `.planning/spikes/CONVENTIONS.md` created or updated with recurring stack/structure/pattern choices
- [ ] `.planning/spikes/WRAP-UP-SUMMARY.md` written for project history
- [ ] Project CLAUDE.md has auto-load routing line

View File

@@ -53,7 +53,8 @@ If no `.planning/spikes/` directory exists, tell the user there's nothing to ana
Otherwise, load in this order:
**a. MANIFEST.md** — the overall idea, requirements, and spike table with verdicts.
**a. MANIFEST.md** — every idea section under `## Ideas` (each idea's paragraph and its own
scoped Requirements) and the `## Spikes` table with verdicts (each row tagged by idea).
**b. Findings skills** — glob `./.claude/skills/spike-findings-*/SKILL.md` and read any that exist, plus their `references/*.md`. These contain curated knowledge from prior wrap-ups.
@@ -74,7 +75,8 @@ If integration risks exist, present them as concrete proposed spikes with names
### Analyze for Frontier Spikes
Think laterally about the overall idea from MANIFEST.md and what's been proven so far. Consider:
Think laterally about every idea section from MANIFEST.md and what's been proven so far for
each. Consider:
- **Gaps in the vision:** Capabilities assumed but unproven.
- **Discovered dependencies:** Findings that reveal new questions.
@@ -86,7 +88,7 @@ Present frontier spikes as concrete proposals numbered from the highest existing
### Get Alignment and Execute
Present all integration and frontier candidates, then ask which to run. When the user picks spikes, write definitions into `.planning/spikes/MANIFEST.md` (appending to existing table) and proceed directly to building them starting at `research`.
Present all integration and frontier candidates, then ask which to run. When the user picks spikes, write definitions into `.planning/spikes/MANIFEST.md` (appending to the existing table, with each row's Idea column set to the idea key(s) it extends or validates) and proceed directly to building them starting at `research`.
</step>
<step name="setup_directory">
@@ -212,33 +214,63 @@ If 2+ credible approaches exist, plan to build quick variants within the spike a
</step>
<step name="create_manifest">
Create or update `.planning/spikes/MANIFEST.md`:
Create or update `.planning/spikes/MANIFEST.md`.
**Assign an idea key.** Derive a short, stable, kebab-case slug (2-4 words) summarizing the
idea being spiked right now, e.g. `realtime-llm-streaming`. Reuse the exact same idea key for
every spike in this session and any later session that continues the same idea. Only mint a
new idea key when the current idea is not a continuation of one already indexed in
MANIFEST.md — never reuse an existing idea key for an unrelated idea, and never merge two
different ideas under one key.
If `.planning/spikes/MANIFEST.md` doesn't exist, create it:
```markdown
# Spike Manifest
## Idea
[One paragraph describing the overall idea being explored]
## Ideas
## Requirements
[Design decisions that emerged from the user's choices during spiking. Non-negotiable for the real build. Updated as spikes progress.]
### {idea-key}
[One paragraph describing this idea]
**Requirements:**
[Design decisions that emerged from the user's choices while spiking THIS idea. Non-negotiable
for the real build of this idea. Updated as spikes progress. Never copy or merge requirements
from a different idea key into this list.]
- [e.g., "Must use streaming JSON output, not single-response"]
- [e.g., "Must support reconnection on network failure"]
## Spikes
| # | Name | Type | Validates | Verdict | Tags |
|---|------|------|-----------|---------|------|
| # | Idea | Name | Type | Validates | Verdict | Tags |
|---|------|------|------|-----------|---------|------|
```
**Track requirements as they emerge.** When the user expresses a preference during spiking, add it to the Requirements section immediately.
If `.planning/spikes/MANIFEST.md` already exists:
- **Same idea key already has a `### {idea-key}` section under `## Ideas`:** append to that
section's Requirements list as new requirements emerge. Never overwrite or rewrite its
`## Idea` paragraph.
- **New idea key, not yet present:** append a new `### {idea-key}` subsection under `## Ideas`,
after any existing idea sections. Never touch, merge into, or delete another idea's section.
- **A pre-#1700 MANIFEST.md with the old flat shape** (a single top-level `## Idea` / `##
Requirements` pair, no `## Ideas` heading): treat its existing content as one implicit idea.
Derive an idea key from its `## Idea` paragraph, migrate it in place to `## Ideas` >
`### {idea-key}` — preserving the paragraph and every existing Requirements bullet and
Spikes row verbatim — then continue as above. Do this migration once; do not repeat it once
`## Ideas` exists.
Every row appended to `## Spikes` carries an **Idea** column set to the idea key it belongs to.
**Track requirements as they emerge.** When the user expresses a preference during spiking, add
it to the current idea's Requirements list immediately — never to a different idea's list.
</step>
<step name="reground">
## Re-Ground Before Each Spike
Before starting each spike (not just the first), re-read `.planning/spikes/MANIFEST.md` and `.planning/spikes/CONVENTIONS.md` to prevent drift within long sessions. Check the Requirements section — make sure the spike doesn't contradict any established requirements.
Before starting each spike (not just the first), re-read `.planning/spikes/MANIFEST.md` and `.planning/spikes/CONVENTIONS.md` to prevent drift within long sessions. Check the current idea's `### {idea-key}` Requirements list — make sure the spike doesn't contradict any established requirement for this idea. Do not apply another idea's requirements.
</step>
<step name="build_spikes">
@@ -287,6 +319,7 @@ Multiple files per spike are expected for complex questions (e.g., `test-basic.j
```markdown
---
spike: NNN
idea: {idea-key}
name: descriptive-name
type: standard
validates: "Given [precondition], when [action], then [expected outcome]"
@@ -337,7 +370,8 @@ tags: [tag1, tag2]
→ Does this match what you expected? Describe what you see.
──────────────────────────────────────────────────────────────
**h.** Update `.planning/spikes/MANIFEST.md` with the spike's row.
**h.** Update `.planning/spikes/MANIFEST.md` with the spike's row, setting the Idea column to
this spike's idea key.
**i.** Commit (if `COMMIT_DOCS` is true):
```bash
@@ -450,10 +484,10 @@ gsd_run query commit "docs(spikes): update conventions" --files .planning/spikes
- [ ] Depth over speed — edge cases tested, surprising findings followed, investigation trail documented
- [ ] Comparison spikes built back-to-back with head-to-head verdict
- [ ] Spikes needing human interaction have forensic log layer
- [ ] Requirements tracked in MANIFEST.md as they emerge from user choices
- [ ] Requirements tracked in MANIFEST.md, scoped to the idea key that produced them, as they emerge from user choices
- [ ] CONVENTIONS.md created or updated with patterns that emerged
- [ ] Each spike README has complete frontmatter, Investigation Trail, and Results
- [ ] MANIFEST.md is current (with Type column and Requirements section)
- [ ] Each spike README has complete frontmatter (including its idea key), Investigation Trail, and Results
- [ ] MANIFEST.md is current (with Idea and Type columns, and each idea's own scoped Requirements section)
- [ ] Commits use `docs(spike-NNN): [VERDICT]` format
- [ ] Consolidated report presented with next-step routing
</success_criteria>