Summary
When an architect has a strong prior on a major decision (language, framework, deployment shape, protocol), that decision should be baked into the issue body before the spec is drafted — not surfaced during the iter-2 CMAP cycle. Today the spec gets drafted against assumed defaults, CMAP feedback addresses the wrong question, and the architect resets the spec mid-flight.
Reporter
Shannon architect, 2026-05-14 ~20:35 PDT via team channel.
Concrete case
Shannon Spec 1353 (Persona harness):
- iter-1: spec drafted in Node design (default assumption)
- iter-2: drop daemon per CMAP feedback
- iter-3: architect intervenes — "actually use Python instead of Node, match
shanutil" (major reset)
- iter-4: CMAP polish
Cost: ~45 min churn rewriting the spec, plus Codex's iter-2 feedback became obsolete the moment the language switched. The architect's "use Python" decision should have been in the original issue body.
Fix shape (two options)
Option A — issue template prompt. Add an optional section to the GitHub issue template (or to the SPIR Specify-phase prompt) explicitly asking the architect for baked architectural decisions that should NOT be reconsidered:
## Baked decisions (architect's strong priors)
<!-- List anything CMAP should treat as fixed: language, framework,
deployment shape, protocol choice, dependency boundaries, etc.
Leave blank if you want the spec to explore tradeoffs freely. -->
Builder treats these as fixed; CMAP doesn't relitigate them.
Option B — pre-spec checklist. A one-pager template the architect fills before filing the issue: language, framework, deployment, key dependencies, deferred-decisions list. Gets embedded into the issue body verbatim.
Option A is lower friction (optional section, ignored if blank). Option B is more rigorous but adds ceremony.
Open questions
- Where does this prompt live — issue template, SPIR builder-prompt, or both?
- Does Codex / Gemini need explicit instruction to honor "baked decisions" as fixed? (Probably yes, in
spec-review.md.)
- Should this be SPIR-only or also apply to AIR / ASPIR?
Adjacent
Shannon noted this is tier-2 priority vs. #742 (bugfix template fix is tier-1). Worth designing carefully rather than rushing.
Suggested protocol
SPIR (needs design discussion) — not a straightforward bugfix.
Summary
When an architect has a strong prior on a major decision (language, framework, deployment shape, protocol), that decision should be baked into the issue body before the spec is drafted — not surfaced during the iter-2 CMAP cycle. Today the spec gets drafted against assumed defaults, CMAP feedback addresses the wrong question, and the architect resets the spec mid-flight.
Reporter
Shannon architect, 2026-05-14 ~20:35 PDT via team channel.
Concrete case
Shannon Spec 1353 (Persona harness):
shanutil" (major reset)Cost: ~45 min churn rewriting the spec, plus Codex's iter-2 feedback became obsolete the moment the language switched. The architect's "use Python" decision should have been in the original issue body.
Fix shape (two options)
Option A — issue template prompt. Add an optional section to the GitHub issue template (or to the SPIR Specify-phase prompt) explicitly asking the architect for baked architectural decisions that should NOT be reconsidered:
Builder treats these as fixed; CMAP doesn't relitigate them.
Option B — pre-spec checklist. A one-pager template the architect fills before filing the issue: language, framework, deployment, key dependencies, deferred-decisions list. Gets embedded into the issue body verbatim.
Option A is lower friction (optional section, ignored if blank). Option B is more rigorous but adds ceremony.
Open questions
spec-review.md.)Adjacent
Shannon noted this is tier-2 priority vs. #742 (bugfix template fix is tier-1). Worth designing carefully rather than rushing.
Suggested protocol
SPIR (needs design discussion) — not a straightforward bugfix.