spec-fixture

# Spec Fixture Turn one brunch feature into a **completed-spec fixture**: a seeded intent graph (requirements, criteria, supporting knowledge, typed edges) with all four interview phases closed, plus a believable interview transcript. The fixture is a real `specification` row in `.brunch/brunch.db`, usable as input to any downstream tooling that consumes a completed spec, or for dogfooding the workspace UI. ## Input `$ARGUMENTS` = a feature + optional profile. - **Feature**: a `memory/SPEC.md` capability-requirement number (e.g. "req 34–36") or a free-form description. - **Profile**: `coverage` (default — maximize graph coverage / stress downstream consumers) or `clean` (tidy demo fixture). Either way, always produce a believable transcript. ## Use when - You need a real completed spec to exercise downstream tooling that consumes one (plan generation, the orchestrator) end-to-end. - You want a self-referential demo spec (brunch speccing a brunch feature). - You want to dogfood the interview/graph UI against realistic data. Not for: editing the product schema, building the downstream tooling itself, or one-off throwaway graphs that don't need to persist. ## Why this works (read before designing) - **Downstream tooling reads the graph snapshot, not the transcript.** It consumes `knowledge_item` + `knowledge_edge`; turn prose is irrelevant to it. So **graph fidelity is for the consumer; the transcript is for the UI/demo**. Get the graph exactly right; make the transcript believable. - **Execution order is not spec truth.** The observer captures *epistemic* deps (assumptions/decisions/constraints point *at* requirements), never req→req execution order. Any downstream ordering is *synthesized* from requirement content. So a faithful fixture seeds **zero req→req `depends_on`** and lets the content imply the order. - **Two unrelated "impact"s.** Turn `impact` (`high|medium|low`, read from `turn.impact`, defaults to `low`) is the interviewer's consequence hint. The edit-impact tier (`none|soft|hard`) is a separate edit-time cascade signal. This skill sets the *turn* impact; it does not touch the cascade tier. ## Method ### Defining the content (optional `ln-*` aids) The fixture *is* an elicitation artifact, so the repo's `ln-*` elicitation skills can shape its content during steps 1–3. Use each skill's **output** to populate the fixture graph — do **not** let them write `memory/SPEC.md` / `PLAN.md`, which are dev-layer planning, not this product-layer fixture data. - **ln-grill** — pressure-test the feature into goals, constraints, and a thorough requirement set (the grounding/design content + supporting nodes). - **ln-disambiguate** — turn vague criteria into concrete behavioral acceptance criteria (sharper `criterion` nodes). - **ln-oracles** — design which criteria verify which requirements (the `verifies` edges) and the "expected downstream behavior" assertions. - **ln-scope** — frame each buildable requirement as a slice with target behavior and acceptance criteria, mirroring requirement → `verifies` → criterion. ### 1. Frame the feature Name it `snake_case`. Decide `mode` (greenfield | brownfield) and delivery posture (incremental feature | end-to-end build). Brownfield + incremental is typical for a feature on existing code, and routes cook output to `<dir>/.brunch/cook/plan.yaml`. ### 2. Design the intent graph Enumerate nodes and edges before writing code. Nodes: `requirement` and `criterion` (the buildable spine) plus supporting `goal` / `term` / `context` / `constraint` / `decision` / `assumption`. Edges are typed and **must satisfy the relationship policy** — see [references/seed-pattern.md](references/seed-pattern.md) for the canonical direction table and the guard. Apply the profile: - **`coverage`** — bake in deliberate stressors so a downstream consumer's full behavior gets exercised (graph read, order synthesis, validation): - Full `verifies` coverage of every *buildable* requirement. - ≥1 criterion that verifies **two** requirements. - ≥1 requirement verified by **multiple** criteria. - ≥1 **non-buildable, constraint-phrased requirement** (typed `requirement`, phrased as a "must not" / invariant) with **no** `verifies` edge — reproduces the real data-quality case a validation pass must catch. - **Zero req→req `depends_on`** — force downstream ordering to be synthesized from content; make the content imply a clear order. - ≥1 adversarial epistemic edge (e.g. `refines` req→req, or assumption/decision/constraint → requirement) that a graph read must **ignore** for ordering. - **`clean`** — well-ordered, every buildable requirement verified, no non-buildables, no adversarial edges. Optimized for a smooth demo run. ### 3. Write the interview-questions doc `docs/fixtures/<name>-interview.md`. It is the source-of-truth and the capture map for the seed. Include: - A "Fixture fidelity" note (transcript reproduced verbatim from the seed). - The four-phase transcript (grounding → design → requirements → criteria) as believable Q&A, each grounding/design question tagged with its `impact`. - The **capture map**: node inventory (ref, kind, content) + edge inventory (canonical for the seed). - **Expected downstream behavior**: assertions for how a consumer reads, orders, and validates the graph, so the end-to-end test has a target. Assign `impact` by the rubric *"how much the answer shapes downstream choices"* (`src/server/prompts/interviewer-grounding.md`): strategic forks, the core goal, and binding constraints are `high`; localized design choices are `medium`; assumptions-to-validate are `low`. Don't make everything `high` — the spread is the signal. ### 4. Author the seed Put `seedAccepted<Feature>Spec(db, projectId)` in its **own file** `src/server/fixtures/scenarios/<name>.ts` (one fixture per file — keeps the `scenarios.ts` registry lean), then import it into `src/server/fixtures/scenarios.ts` and register a `<name>-all-phases-closed` scenario there. Mirror any existing all-phases-closed scenario seed. The seed must: build real grounding/design Q&A turns (set turn-level `impact`), capture each supporting item at the turn that elicits it, accept the requirements + criteria reviews, confirm all four phase outcomes, then add the policy-guarded edges. Full code skeleton and the relation-policy table: [references/seed-pattern.md](references/seed-pattern.md). ### 5. Load + verify - `npm run fix` then `npm run check` — must be green. - Verify the graph against a fresh in-memory DB (counts by kind, edges by relation, four phases confirmed, and the profile's stressors). Use the verification script template in the reference file; delete it after. - Load into the real DB. Re-seeding is **additive**, so to avoid duplicate specs, **delete-then-reseed** (FK-off across spec-scoped tables — snippet in the reference) before `npm run seed -- <name>-all-phases-closed`. ### 6. Reconcile The doc transcript must match the seed **verbatim** — questions, answers, impacts, and captures. If you simplify the seed (e.g. plain Q&A instead of preface cards), update the doc to match, and vice versa. Note any folding (e.g. edge-styling intent folded into a requirement) in the doc's fidelity note. ## Verification checklist - [ ] `npm run check` green. - [ ] In-memory seed asserts expected node/edge counts and the profile's stressors. - [ ] All four phase outcomes confirmed. - [ ] Every buildable requirement has ≥1 `verifies`; non-buildables have none. - [ ] Every edge passes `supportsKnowledgeRelationship`. - [ ] Doc transcript matches the seeded turns verbatim (incl. per-turn impact). - [ ] Real DB has exactly one spec for this feature (no stale duplicates).