* 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:
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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>
|
||||
|
||||
Reference in New Issue
Block a user