fix(molecules): take Level 1 from a linked requirement doc in design-blueprint

[ShuratCode]

Problem

When a feature has a linked requirement doc, design-blueprint still walks Level 1 (Capabilities) with the user. The spec's Scope and Scenarios were already agreed in the requirement-forge interview, and they are exactly what Level 1 asks for. So the user agrees the same outcomes twice.

In one project that uses requirement-forge before design-blueprint, 164 context docs link a spec. At least 33 of them log an [Entry] decision like "start at Level 2 — Level 1 is redundant with the spec". Users kept skipping Level 1 by hand.

Root cause

• design-first's Complexity Calibration picks the entry level from task size only. It never asks whether scope is already agreed.
• design-blueprint reads requirement_doc in Step 1, but only for ## Technical Constraints. Scope and Scenarios never reach the Entry Assessment.
• The resume check sent a doc with no saved level straight to Level 1, past the Entry Assessment.

Change

• Spec as Level 1 (Step 2): when the context doc has no ## Design: Level section yet and requirement_doc resolved to the spec itself (not pasted constraints only), the spec is Level 1. It is not re-validated; spec quality belongs to requirement-forge, the same way Technical Constraints are trusted today.
• Entry level: it proposes Level 2 or the calibrated level, whichever is later, and offers: "Level 1 comes from the linked spec. Starting at Level [N]. Want a capabilities walk-through first?" Yes enters Level 1 with the spec as input.
• Persistence: otherwise Level 1 is saved as a one-line pointer to the spec, with nothing copied. The Step 3 completeness check still passes.
• Resume check (Step 1): a doc with no saved level now goes through the Entry Assessment instead of being forced to Level 1. This also changes behavior when no spec is linked: such a doc gets the normal Entry Assessment again rather than a fixed Level 1.
• Docs and build: docs/practical-guide.md describes the handoff, and skills/ is regenerated with tools/build-skills.sh.

Gates for Levels 2–4, the regression rule and the drift check are unchanged.

Verification

There is no automated test harness for skill behavior. I checked the rule against 317 real requirement-forge specs and the 164 context docs that link them. A fresh-eyes review (an implementation pass, a cross-model Codex pass, and a security pass) caught the resume-path gap, which is fixed here.

🤖 Generated with Claude Code

[techygarg]

Thanks @ShuratCode! It's great to see how much your team uses Lattice. Data from 164 real context docs is exactly the feedback we can't get any other way. The problem is clear: people were skipping Level 1 by hand because the spec already covers it. Let's fix it.

I've been thinking it through, and here's where I've landed. I'd really like your view, since you see far more real usage than we do.

My thinking: design-blueprint should take the spec as the source of truth and not check it again. Checking specs is what requirement-forge and the requirement-quality atom are for. design-blueprint already does this with ## Technical Constraints, which it accepts without questioning. Scope and Scenarios could work the same way.

If we go with that, a few parts of the PR could be simpler:

• The check for a filled ## Scope and at least one ### Scenario: a resolved spec could be enough.
• The question "Do the spec's scenarios still cover what this design must deliver?" and the fallback to Level 1 on "no": this feels like a second review of the requirements.
• The exceptions for open scope questions and for several specs.
• "STOP: do not re-walk Level 1": once the rest is trimmed, it might stop the agent from doing Level 1 when the user actually asks for it.

That said, you may have added some of these because of things you saw in practice. Did you hit cases where a thin or unfinished spec caused problems in design? If so, that would change my view. Those checks might then belong in requirement-quality, so every spec gets them.

One idea to add: in many teams a BA writes the spec and a developer does the design. That developer might want a quick capabilities walk-through to understand the spec. So when entering at Level 2, we could offer it: "Level 1 comes from the linked spec. Starting at Level 2. Want a capabilities walk-through first?"

A rough version of the rule:

**Spec as Level 1**: when the context doc has no `## Design: Level` section yet and `requirement_doc` resolved to the spec itself (not pasted constraints only), the spec is Level 1. Do not re-validate it.
- Propose entry at Level 2 or the calibrated level, whichever is later, and offer: "Level 1 comes from the linked spec. Starting at Level [N]. Want a capabilities walk-through first?"
- User wants the walk-through → enter at Level 1, using the spec as input.
- Otherwise, save `## Design: Level 1 -- Capabilities` as one line: `Taken from [{spec-file}](../requirements/features/{spec-file}). Not re-walked.` Do not copy the spec.

What I'd keep as is: the Level 1 pointer, the "Level 2 or the calibrated level, whichever is later" rule, and the resume-check fix. That last one is a great catch. Small notes: the resume fix also changes behavior when there's no spec, so the description could mention it. And since nothing checks whether the spec is approved, the title could say "linked requirement doc" instead of "approved spec".

For teams that always want Level 1 (for example, where BAs write every spec): rather than a config flag, I think this fits an idea we posted in discussion #50, a short per-molecule additional_instructions entry in .lattice/config.yaml:

additional_instructions:
  design_blueprint: "Walk Level 1 even when a requirement doc is linked."

It's not part of this PR, but with your team's experience, your thoughts on #50 would be really valuable.

A few questions for you:

1. In your team, does the same person usually run requirement-forge and design-blueprint, or is it split between people?
2. Would the walk-through opt-in get used, or would people almost always skip it?
3. Would additional_instructions work for your setup, or do you need something different?

Thanks again, this is a really useful contribution!

[ShuratCode]

Thanks @techygarg, this makes sense. I pushed your simpler version in 4c01628. The linked requirement doc is trusted as Level 1, with no content check and no coverage question. The design offers the walk-through and keeps the pointer, the "Level 2 or later" rule and the resume fix. I also updated the title and the description.

Thin specs: I did not see real cases where a thin or unfinished spec caused problems in design. I added those checks after a review pass, not because of real usage, so dropping them matches what we see.

Spec updates after design: What we do see is the other direction. After design-blueprint, and after plan reviews (eng, design, devex), we sometimes need to update the requirements. In our data, 95 of 319 specs carry at least one Design override line from the Step 3 drift check. This is one more reason the one-line Level 1 pointer is right: the spec stays the single source, so a later update can't leave a stale capabilities list in the context doc. Changes that come from reviews after design-blueprint have no path back to the spec today. We update the spec by hand.

1. Who runs the skills: On our team, one person takes a ticket end to end: requirement-forge → design-blueprint → design review → code-forge → a self-review → PR and merge. The design review is usually a self-review with gstack skills (/plan-eng-review, for example): 23 of the 30 designs since we made it a rule on 2026-09-22 record one. Sometimes a teammate reviews too. So the person in design-blueprint usually wrote the spec a few hours earlier.

2. The walk-through: Most people would skip it. The context is fresh, and we are often coding within a few hours. It would mainly help on big designs. The offer goes in the same message as the entry-level confirmation, so it adds no extra round trip. That seems like the right cost for a rarely used option.

3. additional_instructions: For us, the open question is less about forcing Level 1. It is about when and how to bring a second person into the architecture and design review. The self-review with gstack skills runs on most designs, but not all. A human review happens only sometimes, and for big decisions we share a doc with the team (most people review it with AI help). A way to mark a design for team review, or a review step after design-blueprint, would help us more than a Level 1 switch. I'll add our thoughts on #50.

Edited: updated the numbers with current data. The self-review runs on most designs, not on all of them.

[techygarg]

Looks good — thanks @ShuratCode for the quick turnaround and the detailed data. Approving.