Problem
When a project is scaffolded from this template and the discovery Q&A (Step 1) specifies a non-CLI delivery mechanism (e.g., "browser-based", "web app"), the architecture step (Step 2) has no checkpoint to catch the mismatch with the template's CLI-only codebase. The SA can inherit the CLI bias from the existing __main__.py / argparse structure and design a CLI architecture for a product that the discovery Q&A explicitly says should be browser-based.
This happened in practice: a browser-based product was scaffolded from the template, discovery correctly captured "browser-based" and "in a web browser", but the SA nearly produced a CLI architecture because the template's existing code and system.md implicitly biased toward the inherited CLI architecture. The stakeholder had to intervene mid-Step-2 to correct course.
Root Cause
The workflow has no checkpoint between Step 1 and Step 2 that requires the SA to explicitly reconcile:
- The delivery mechanism identified in discovery Q&A
- The current codebase architecture inherited from the template
Recommendations
-
Add a delivery-mechanism checkpoint to the architect skill: Before designing domain stubs, the SA should explicitly answer: "What delivery mechanism does the discovery Q&A specify, and does the current codebase match it?" If there's a mismatch, the SA must flag it and make the architecture pivot an ADR before proceeding.
-
Add a delivery-mechanism field to system.md: Include a top-level field like Delivery: CLI | Web | API | Desktop that the SA sets during Step 2 and reconciles against discovery Q&A.
-
Consider adding a setup-project question: When initialising from the template, ask "What delivery mechanism will this project use?" and scaffold accordingly (CLI → argparse stub, Web → Flask/FastAPI stub, API → FastAPI stub). This would prevent the mismatch from occurring in the first place.
Impact
- Wasted SA effort on architecture that assumed the wrong entry point
- Stakeholder had to intervene manually
- Feature branch had to be paused mid-Step-2
Problem
When a project is scaffolded from this template and the discovery Q&A (Step 1) specifies a non-CLI delivery mechanism (e.g., "browser-based", "web app"), the architecture step (Step 2) has no checkpoint to catch the mismatch with the template's CLI-only codebase. The SA can inherit the CLI bias from the existing
__main__.py/ argparse structure and design a CLI architecture for a product that the discovery Q&A explicitly says should be browser-based.This happened in practice: a browser-based product was scaffolded from the template, discovery correctly captured "browser-based" and "in a web browser", but the SA nearly produced a CLI architecture because the template's existing code and
system.mdimplicitly biased toward the inherited CLI architecture. The stakeholder had to intervene mid-Step-2 to correct course.Root Cause
The workflow has no checkpoint between Step 1 and Step 2 that requires the SA to explicitly reconcile:
Recommendations
Add a delivery-mechanism checkpoint to the architect skill: Before designing domain stubs, the SA should explicitly answer: "What delivery mechanism does the discovery Q&A specify, and does the current codebase match it?" If there's a mismatch, the SA must flag it and make the architecture pivot an ADR before proceeding.
Add a delivery-mechanism field to system.md: Include a top-level field like
Delivery: CLI | Web | API | Desktopthat the SA sets during Step 2 and reconciles against discovery Q&A.Consider adding a setup-project question: When initialising from the template, ask "What delivery mechanism will this project use?" and scaffold accordingly (CLI → argparse stub, Web → Flask/FastAPI stub, API → FastAPI stub). This would prevent the mismatch from occurring in the first place.
Impact