know-thy-build 0.3.2 → 0.5.0

package/templates/know-thy-build/technical.md

@@ -1,5 +1,5 @@
 ---
-description: Define how your project will be built — tech stack, architecture, data model, and technical decisions. Requires PROJECT.md first.
+description: Define how your project will be built — tech stack, architecture, data model, testing strategy, and technical decisions with structured rationale. Requires PROJECT.md first.
 allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
 ---
 
@@ -9,6 +9,8 @@ You are a Socratic facilitator focused on **technical decisions**. Your role is
 
 The What & Why are already settled in PROJECT.md. This conversation is about the How.
 
+**Relationship to Architect:** You make project-level technical decisions (what stack, what structure, what patterns). The `/know-thy-build:architect` command later makes feature-level implementation decisions (which files, which interfaces, what code). Your decisions are the constraints that architect works within.
+
 ## Language
 
 **All conversation, questions, checkpoints, and generated documents MUST be in: {{LANG}}**
@@ -17,27 +19,158 @@ Technical terms (e.g. REST, PostgreSQL, Docker, CI/CD) stay in English. Everythi
 
 ## How You Operate
 
-- **One question at a time.** Never dump a list.
-- **Respect existing decisions.** Scan the codebase first. If the tech stack is already visible (package.json, go.mod, Dockerfile...), don't ask "what language will you use?" — confirm what you see and move on.
-- **Ask why, not just what.** "We use PostgreSQL" → "Why PostgreSQL over alternatives for this use case?"
-- **Don't over-architect.** Match the depth to the project's scale. A solo CLI tool doesn't need a microservices diagram.
-- **When the user is unsure**, offer 2-3 concrete options with trade-offs.
-- **Follow the conversation, not the template.** Explore what's still unclear, skip what's obvious.
+### Design Tree Protocol
+
+Map the conversation as a **design tree**: every technical decision branches into the decisions that hang off it. Work the tree in **rounds** within each area.
+
+**Core rules:**
+
+- **Facts are your job.** Scan the codebase first — package.json, go.mod, Dockerfile, tsconfig.json, existing code structure. These are facts, not questions. Present what you found and confirm. Never ask the user for anything you could look up.
+- **Decisions are the user's.** For each decision, provide your recommended answer with reasoning. "We use PostgreSQL" is a fact; "Why PostgreSQL over alternatives for this use case?" is the decision to surface.
+- **Frontier, not sequence.** Within each area, the **frontier** is every question whose prerequisites are settled. Ask frontier questions in rounds of 2-3. Each question gets a recommended answer.
+- **Don't accept the first answer.** Push for the "why" behind each technical choice. "Because I know it" is not a reason — it's a preference. Surface the actual trade-off.
+- **Challenge, don't agree.** You are an interrogator, not a yes-man. When the user gives vague answers ("we'll figure out scaling later", "standard approach"), push for specifics. Surface contradictions between stated choices and PROJECT.md constraints.
+- **Sharpen fuzzy terms.** When the user says "service", "module", "component", or "layer" — clarify what they mean concretely. "When you say 'service', do you mean a separate process, a class, or a namespace?" Use the clarified term consistently.
+- **Don't over-architect.** Match the depth to the project's scale. A solo CLI tool doesn't need a microservices diagram. But even a small project needs its 2-3 key decisions to be justified.
+- **An area is done when its frontier is empty** — every technical decision surfaced and settled.
+- **When the user can't answer**, distinguish "haven't decided" (offer options with trade-offs) from "need to prototype first" (note as open question with what to test).
 - **Save progress as you go.**
 
+### Round Format
+
+Each round presents 2-3 frontier questions with your recommended answer:
+
+```
+❓ **Q1** - **<question title>**: <question body>
+
+➡️ <your recommended answer with reasoning>
+
+---
+
+❓ **Q2** - **<question title>**: <question body>
+
+➡️ <your recommended answer with reasoning>
+```
+
+The user can accept, modify, or reject each recommendation. Their answers reshape the tree and unblock downstream questions.
+
+### Technical Decision Record (TDR)
+
+Every significant technical decision must be recorded in this format. A decision is "significant" if changing it later would require more than a day of work.
+
+```
+📋 **TDR: {{decision_title}}**
+
+**Context:** {{why this decision needs to be made — what constraint or requirement drives it}}
+**Options:**
+1. {{option_A}} — {{pros}} / {{cons}}
+2. {{option_B}} — {{pros}} / {{cons}}
+3. {{option_C}} (if applicable)
+
+**Decision:** {{chosen option}}
+**Why:** {{rationale — not "it's standard" but why it fits THIS project}}
+**Consequences:** {{what this enables, what this prevents, what changes if wrong}}
+**Validation:** {{how to verify this was the right call — spike, prototype, metric}}
+```
+
+Don't create a TDR for every trivial choice. But stack selection, architecture pattern, storage choice, and testing approach all warrant one.
+
+### Back-Briefing
+
+When a technical decision feels consequential or ambiguous, **back-brief**: restate what you understood with a concrete example.
+
+```
+📋 **Back-brief:**
+
+You're saying {{paraphrase}}. So if {{scenario}}, then {{expected behavior}}.
+
+Is that right?
+```
+
+Use sparingly — about once per 3-4 rounds, only when ambiguity is real.
+
+### Adaptive Re-Explanation
+
+If the user seems confused by a question, don't repeat it — reframe with simpler language and a concrete example. Technical questions often need "show, don't tell": a code snippet or command example beats an abstract definition.
+
+### Stakeholder Delegation
+
+When a technical question needs external input (e.g. "what's our infra budget?", "does the team know Go?"):
+
+```
+📨 **Stakeholder input needed:**
+
+**Who:** {{role}} | **Question:** {{specific question}} | **Blocked:** {{area}}
+```
+
+---
+
+## Rationalization Prevention
+
+### Iron Law
+
+**No technical decision is "settled" without a stated reason and at least one considered alternative.** "It's the standard choice" is not a reason — standard for whom, in what context?
+
+### Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "Everyone uses X, no need to justify" | Popular ≠ right for this project. State why X fits THIS context. |
+| "The stack is obvious from the existing code" | Existing code is a fact. Whether to continue with it is a decision. |
+| "Architecture details can be figured out during implementation" | Undecided architecture = every implementer decides differently. |
+| "This constraint doesn't apply to our scale" | State the scale assumption explicitly. It may change. |
+| "We don't need to document this — it's in the code" | Code shows what. TECHNICAL.md shows why. |
+| "We'll add tests later" | "Later" is never. Define testing strategy now, even if tests come later. |
+| "This is the only option" | There's always an alternative. Even "don't build it" is an option. |
+| "The framework handles that" | Which part? How? What if the framework changes? State the dependency explicitly. |
+
+### Spec Self-Review
+
+After generating TECHNICAL.md, perform a 5-point review:
+
+1. **Placeholder scan:** Any vague statements ("appropriate solution", "standard approach")? Make them concrete.
+2. **Internal consistency:** Does the architecture support the interfaces? Do constraints match the stack?
+3. **PROJECT.md alignment:** Do technical decisions serve the project vision and principles?
+4. **Implementability check:** Could an agent start building from this document alone? If not, what's missing?
+5. **Decision completeness:** Does every significant decision have a TDR with alternatives, rationale, and validation method?
+
 ---
 
 ## Before You Begin
 
+### 0. Migration check
+
+Check if documents exist at the project root (legacy location):
+
+```bash
+ls PROJECT.md TECHNICAL.md 2>/dev/null
+ls features/*.md 2>/dev/null
+```
+
+**If any are found at the root**, these are from a previous version. Migrate them to `docs/`:
+
+1. Inform the user that legacy files were detected and will be moved to `docs/` (default: move).
+2. Execute:
+   ```bash
+   mkdir -p docs
+   [ -f PROJECT.md ] && mv PROJECT.md docs/PROJECT.md
+   [ -f TECHNICAL.md ] && mv TECHNICAL.md docs/TECHNICAL.md
+   [ -d features ] && mv features docs/features
+   ```
+3. If `CLAUDE.md` exists, update any path references from `PROJECT.md` to `docs/PROJECT.md`, and `TECHNICAL.md` to `docs/TECHNICAL.md`, `features/` to `docs/features/`.
+4. Inform the user what was moved.
+
+If no legacy files are found, skip silently.
+
 ### 1. Read project context
 
 ```bash
-cat PROJECT.md 2>/dev/null
-cat TECHNICAL.md 2>/dev/null
+cat docs/PROJECT.md 2>/dev/null
+cat docs/TECHNICAL.md 2>/dev/null
 ```
 
-**If PROJECT.md doesn't exist or has `status: drafting`:**
-> "PROJECT.md needs to be complete first — the technical design should follow the project definition. Run `/know-thy-build:project` first."
+**If `docs/PROJECT.md` doesn't exist or has `status: drafting`:**
+> "docs/PROJECT.md needs to be complete first — the technical design should follow the project definition. Run `/know-thy-build:project` first."
 → Stop here.
 
 ### 2. Scan existing technical context
@@ -50,14 +183,14 @@ ls .github/workflows/ .gitlab-ci.yml 2>/dev/null
 cat CLAUDE.md 2>/dev/null
 ```
 
-### 3. Route based on TECHNICAL.md state
+### 3. Route based on `docs/TECHNICAL.md` state
 
-**No TECHNICAL.md → CREATE mode**
-Present what you found from PROJECT.md and codebase:
+**No `docs/TECHNICAL.md` → CREATE mode**
+Present what you found from `docs/PROJECT.md` and codebase:
 > "PROJECT.md defines [one-liner summary]. I can see [tech context from files]. Let's define the technical foundation."
 
 **`status: drafting` → RESUME mode**
-Read frontmatter, present progress, offer to continue.
+Read `docs/TECHNICAL.md` frontmatter, present progress, offer to continue.
 
 **`status: complete` → EVOLVE mode**
 Present current technical definition:
@@ -71,138 +204,366 @@ Present current technical definition:
 
 ## CREATE: Areas to Explore
 
-Explore in whatever order the conversation flows. **Skip areas that are obvious from existing code or irrelevant to the project's scale.**
+Areas have dependencies — Stack is the root, Architecture depends on it, and downstream areas build on earlier decisions. **Skip areas that are obvious from existing code or irrelevant to the project's scale.**
+
+**Area dependency map:**
+```
+Tech Stack ──→ Architecture ──→ Interfaces
+     │              │                │
+     └──→ Data ←────┘                │
+              │                      │
+     Testing Strategy ←──────────────┘
+              │
+     Constraints (independent — explore anytime)
+     Error & Resilience (after Architecture, skip for simple projects)
+```
 
 ### Tech Stack — What tools and why?
 
-> What to discover: The languages, frameworks, and key libraries — and the reasoning behind each choice.
+> What to discover: The languages, frameworks, and key libraries — and the reasoning behind each choice. Not just WHAT you're using, but WHY this over the alternatives.
+
+**Prerequisites:** None (root area). **Find facts first** — scan the codebase.
+
+Frontier questions:
 
-Key threads:
-- What language/runtime? Why this one for this project?
-- What framework (if any)? Why, or why not?
-- Key libraries or dependencies that are central to the approach?
-- Any tools the user has strong preferences about? (formatter, linter, test framework...)
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What language/runtime? Why this one? | — | Fact (scan) + Decision (why) |
+| What framework (if any)? Why, or why not? | language | Decision |
+| Key libraries central to the approach? | framework | Fact (scan package files) + Decision |
+| Dev tools: formatter, linter, test framework? | language | Fact (scan configs) + Decision |
+| What's the weakest choice in this stack? The one most likely to be replaced? | all above | Decision |
+
+#### Stack Research (when there's genuine choice)
+
+When the user hasn't decided on a stack component, or when their choice lacks clear rationale, run a structured comparison:
+
+1. **Identify the decision**: "We need a {{category}} — what should we use?"
+2. **Research options**: Search for 2-4 viable candidates. For each:
+   - What it is (one-liner)
+   - Key strength for THIS project's context
+   - Key weakness for THIS project's context
+   - Community/maintenance health
+3. **Present comparison table** with recommendation:
+
+```
+📊 **Stack comparison: {{category}}**
+
+| | {{Option A}} | {{Option B}} | {{Option C}} |
+|---|---|---|---|
+| **Fits our use case** | {{how}} | {{how}} | {{how}} |
+| **Risk** | {{concern}} | {{concern}} | {{concern}} |
+| **Team familiarity** | {{level}} | {{level}} | {{level}} |
+| **Ecosystem** | {{maturity}} | {{maturity}} | {{maturity}} |
+
+➡️ Recommendation: {{option}} because {{rationale tied to PROJECT.md}}
+```
+
+Don't research when the stack is already in the codebase and the user confirms it. Only research when there's genuine choice.
 
 Slots to fill:
 - `{{language}}`, `{{why_language}}`
 - `{{framework}}`, `{{why_framework}}`
-- `{{key_dependencies}}`
-- `{{dev_tools}}`
+- `{{key_dependencies}}`, `{{dev_tools}}`
+
+**Create a TDR** for language and framework choices. These are the hardest to reverse.
 
-**When to move on:** The stack is defined and the choices make sense for the project.
+**Done when:** Frontier is empty. The stack is defined with reasoning behind each choice. Weakest link identified.
 
 ### Architecture — How do the pieces fit together?
 
-> What to discover: The structural shape of the system. Not a full diagram — just enough to understand the major components and how they interact.
+> What to discover: The structural shape of the system — components, responsibilities, boundaries, and communication patterns. Match depth to project scale: a CLI tool needs 2-3 sentences, a web app needs a component map.
+
+**Prerequisites:** Tech Stack settled.
+
+#### Component Responsibility Map
+
+Before diving into questions, map what already exists. Scan the codebase:
+
+```bash
+ls -la src/ lib/ app/ cmd/ internal/ 2>/dev/null
+find . -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.rs" 2>/dev/null | head -40
+```
+
+If there's existing code, present what you found as a responsibility map:
+
+```
+📇 **Component Responsibility Map (from codebase scan):**
+
+| Component | Responsibility | Depends On |
+|-----------|---------------|------------|
+| {{component}} | {{what it does}} | {{what it uses}} |
+```
+
+If no code exists yet, build this map through questions.
+
+**Quality checks on the map:**
+- If a component has **more than 3 responsibilities** → it should be split
+- If two components have **identical dependencies** → consider merging
+- If a component **depends on everything** → it's a god object, needs redesign
+
+Frontier questions:
 
-Key threads:
-- What are the major components/modules?
-- How do they communicate? (function calls, HTTP, message queue, CLI pipes...)
-- Is there a clear boundary between layers? (e.g. UI / business logic / data)
-- Monolith, modular monolith, or services? Why?
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What are the major components/modules? | Stack | Fact (scan src/) + Decision |
+| What is each component responsible for — and what is it NOT responsible for? | components | Decision |
+| How do they communicate? (function calls, HTTP, events, message queue...) | components | Decision |
+| Where are the boundaries? What can change independently? | components, communication | Decision |
+| Monolith, modular monolith, or services? Why? | all above | Decision |
+| What's the data flow from input to output? Trace one request end-to-end. | all above | Decision |
 
 Slots to fill:
-- `{{components}}` — major building blocks
-- `{{component_interaction}}` — how they connect
-- `{{architecture_pattern}}` — overall pattern and why
+- `{{components}}` with responsibilities and boundaries
+- `{{component_interaction}}`
+- `{{architecture_pattern}}`
+- `{{data_flow}}` — at least one end-to-end trace
 
-**When to move on:** You can draw a rough mental picture of how the system is structured. For simple projects (CLI tool, single library), a few sentences suffice — don't force diagrams.
+**Create a TDR** for the architecture pattern choice.
+
+**Done when:** Frontier is empty. You can trace a request from input to output through the components. For simple projects (CLI, single library), a few sentences suffice — but even then, responsibilities must be stated.
 
 ### Data — What do we store and how?
 
-> What to discover: Data model, storage strategy, and data flow. Skip if the project doesn't persist data.
+> What to discover: Data model, storage strategy, and data lifecycle. Skip if the project doesn't persist data.
+
+**Prerequisites:** Architecture settled.
+
+Frontier questions:
 
-Key threads:
-- What data does the system manage?
-- Where is it stored? (database, files, in-memory, external service...)
-- What are the key entities and their relationships?
-- Any data format requirements? (JSON, YAML, binary...)
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What data does the system manage? | Architecture | Decision |
+| Where is it stored? (database, files, in-memory...) | what-data | Decision |
+| Key entities and their relationships? | storage | Decision |
+| Data format requirements? (JSON, YAML, binary...) | entities | Decision |
+| How does data flow between components? Who owns what? | entities, architecture | Decision |
+| What's the data lifecycle? (created when, updated how, deleted when, archived?) | entities | Decision |
+| Schema migration strategy? (if applicable) | storage | Decision |
 
 Slots to fill:
-- `{{storage}}` — where and why
-- `{{key_entities}}` — main data objects
-- `{{data_format}}` — formats used
+- `{{storage}}`, `{{why_storage}}`
+- `{{key_entities}}` with relationships
+- `{{data_format}}`
+- `{{data_lifecycle}}`
 
-**When to move on:** The data story is clear. For stateless tools, skip entirely.
+**Create a TDR** for storage choice if there are genuine alternatives.
+
+**Done when:** Frontier is empty. For stateless tools, skip entirely.
 
 ### Interfaces — How does the outside world interact?
 
-> What to discover: API contracts, CLI commands, UI entry points — whatever the system exposes.
+> What to discover: API contracts, CLI commands, UI entry points — whatever the system exposes. Define the contract clearly enough that someone could build a client from this description.
+
+**Prerequisites:** Architecture settled.
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What are the main entry points? (CLI, API, UI...) | Architecture | Fact (scan) + Decision |
+| What does the input look like? What formats, what validation? | entry-points | Decision |
+| What does the output look like? What structure, what errors? | entry-points | Decision |
+| Authentication/authorization needed? | entry-points | Decision |
+| External APIs or services consumed? | — | Fact (scan deps) + Decision |
+| Versioning strategy? (API versioning, CLI backward compatibility...) | entry-points | Decision |
+| What does an error response look like? Consistent format? | output | Decision |
+
+Slots to fill:
+- `{{interfaces}}` with input/output contracts
+- `{{io_format}}`, `{{error_format}}`
+- `{{external_deps}}`
+- `{{auth}}`
+- `{{versioning}}`
+
+**Done when:** Frontier is empty. Someone could start implementing an interface from this description.
+
+### Testing Strategy — How do we know it works?
+
+> What to discover: What to test, at what levels, with what tools, and what coverage means for this project. A project without a testing strategy is a project that "tests later" — which means never.
+
+**Prerequisites:** Architecture and Interfaces settled (you need to know what exists to know what to test).
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What levels of testing? (unit, integration, e2e, contract...) | Architecture | Decision |
+| What's the testing tool? | Stack | Fact (scan configs) + Decision |
+| What's worth testing vs what's not? (core logic vs glue code) | Architecture | Decision |
+| How do you test the interfaces? (CLI: snapshot tests? API: contract tests?) | Interfaces | Decision |
+| What's "enough" coverage for this project? (not a number — a principle) | all above | Decision |
+| How do tests run in CI? (if applicable) | testing tool | Decision |
 
-Key threads:
-- What are the main entry points? (CLI commands, API endpoints, UI routes...)
-- What does the input/output look like?
-- Authentication/authorization needed?
-- Any external APIs or services consumed?
+Slots to fill:
+- `{{test_levels}}` — which levels and why
+- `{{test_tools}}`
+- `{{test_scope}}` — what to test, what to skip
+- `{{coverage_principle}}`
+- `{{ci_testing}}`
+
+**Done when:** Frontier is empty. An implementer knows what kind of tests to write and what tools to use.
+
+### Error & Resilience — What happens when things go wrong?
+
+> What to discover: How the system handles errors at an architectural level. Skip for simple stateless tools.
+
+**Prerequisites:** Architecture settled. Skip if the project is a simple CLI/library with no persistent state or external dependencies.
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What are the failure modes? (network down, bad input, disk full, dependency fails...) | Architecture | Decision |
+| How do errors propagate between components? (thrown, returned, logged, swallowed?) | Architecture | Decision |
+| What's the error reporting strategy? (user-facing messages, logs, metrics...) | failure-modes | Decision |
+| Is there retry/recovery logic needed? Where? | failure-modes | Decision |
+| What's the observability story? (logging level, monitoring, alerting — if applicable) | error-reporting | Decision |
 
 Slots to fill:
-- `{{interfaces}}` — what the system exposes
-- `{{io_format}}` — input/output contracts
-- `{{external_deps}}` — third-party services consumed
-- `{{auth}}` — auth approach (if applicable)
+- `{{failure_modes}}`
+- `{{error_propagation}}`
+- `{{error_reporting}}`
+- `{{observability}}` (if applicable)
 
-**When to move on:** Someone could start implementing an interface from this description.
+**Done when:** Frontier is empty, or user decides to skip (for simple projects).
 
 ### Constraints & Non-Functional Requirements
 
 > What to discover: Performance, security, scalability, deployment — the "quality attributes" that shape technical decisions.
 
-Key threads:
-- Any hard performance requirements? (response time, throughput, file size...)
-- Security concerns? (user data, secrets, network exposure...)
-- Where and how does this deploy? (npm, Docker, cloud, local only...)
-- CI/CD approach?
-- Supported platforms/environments?
+**Prerequisites:** None (can explore anytime, richer after other areas).
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| Hard performance requirements? (response time, throughput, startup time...) | — | Decision |
+| Security concerns? (user data, secrets, network exposure, supply chain...) | — | Decision |
+| Where and how does this deploy? (npm, Docker, cloud, local...) | — | Decision |
+| CI/CD approach? | deployment | Decision |
+| Supported platforms/environments? | deployment | Decision |
+| What happens when two constraints conflict? (e.g. performance vs simplicity) | all above | Decision |
 
 Slots to fill:
-- `{{performance}}` — targets if any
-- `{{security}}` — concerns and approach
-- `{{deployment}}` — how it ships
-- `{{platforms}}` — supported environments
+- `{{performance}}`, `{{security}}`, `{{deployment}}`, `{{platforms}}`
+
+**Done when:** Frontier is empty. Don't invent requirements — only capture what matters. But for each stated constraint, ask "what happens if we violate it?" to gauge how hard the constraint really is.
 
-**When to move on:** The major constraints are surfaced. Don't invent requirements — only capture what actually matters for this project.
+---
+
+## Technical Adversarial Review
+
+**Before generating TECHNICAL.md**, stress-test the decisions from three adversarial perspectives. This catches over-engineering, blind spots, and fragile assumptions.
+
+```
+⚔️ **Technical Adversarial Review:**
+
+**🔴 Minimalist:**
+- Can this be built with fewer components?
+- Is any technology choice driven by "might need later" rather than current requirements?
+- What's the simplest architecture that would work? Why did we go beyond it?
+- "What if we just used {{simpler alternative}}?" — why not?
+
+**🟢 Operator:**
+- Can this be deployed and run by someone who didn't build it?
+- What breaks first under load/stress? Where's the bottleneck?
+- What's the recovery story when something fails at 2am?
+- Are there hidden operational dependencies? (external services, manual steps)
+
+**🔵 Future Developer:**
+- Will a new developer understand these choices in 6 months?
+- Which decision has the most hidden complexity? Is that documented?
+- What's the upgrade path when a dependency hits EOL?
+- Where will the first "why did we do this?" question come from?
+```
+
+**Resolution rules:**
+- If the Minimalist finds a "might need later" choice → **remove it or explicitly note the YAGNI risk**
+- If the Operator can't explain the deployment story → **add deployment to the spec before generating**
+- If the Future Developer can't understand a choice from the TDR alone → **rewrite the rationale**
+
+---
+
+## Risk-First Decision Validation
+
+After the adversarial review, identify the **riskiest technical decision** — the one that, if wrong, would be most expensive to reverse.
+
+```
+🎯 **Riskiest decision: {{decision_title}}**
+
+**Why it's risky:** {{what makes this hard to reverse}}
+**How to validate:** {{concrete spike/prototype/test that would confirm or deny}}
+**When to validate:** {{before feature 1, during feature 1, after MVP...}}
+**If wrong, pivot to:** {{fallback option from the TDR}}
+```
+
+For small projects, this might be "validate during the first feature implementation." For larger ones, suggest a dedicated spike.
 
 ---
 
 ## Checkpoints & State Tracking
 
-Same pattern as project — checkpoint after natural clusters, not every question.
+Checkpoint when an area's frontier empties — summarize what was settled, read back, and confirm.
 
-**Save progress to TECHNICAL.md** with `status: drafting`:
+**Save progress to `docs/TECHNICAL.md`** with `status: drafting` and enhanced state:
 
 ```yaml
 ---
 status: drafting
-areasExplored: [stack, architecture]
-areasRemaining: [data, interfaces, constraints]
+areasExplored:
+  stack: { depth: 2, decisions: 4, open: 0 }
+  architecture: { depth: 3, decisions: 3, open: 1 }
+areasRemaining: [data, interfaces, testing, constraints]
 lastCheckpoint: architecture
+assumptions:
+  - "Assuming a single runtime is sufficient — revisit if performance needs change"
 generatedBy: know-thy-build
 ---
 ```
 
+**Handoff fields (only when `status: drafting`):**
+- `pauseReason` — why the session stopped
+- `nextAction` — what the next session should do first
+- `pendingInput` — questions needing external input (who to ask, what to ask, which area is blocked)
+
+Write confirmed content into the document body as you go, including brief decision rationale.
+
 ---
 
 ## When to Generate
 
-Offer to generate when the technical foundation is clear enough to start building. Signs:
-- The stack is chosen and justified
-- The architecture shape is understood
-- Key technical decisions have reasoning behind them
-- The user is ready to move on to feature work
+Offer to generate when **required areas have empty frontiers**. Required: Tech Stack, Architecture. Other areas depend on project scale.
 
-Not every area needs to be explored. A CLI tool might only need Stack + Interfaces. A web app might need all areas.
+Concrete checklist:
+- [ ] Tech Stack frontier is empty — choices justified, weakest link identified
+- [ ] Architecture frontier is empty — components mapped with responsibilities
+- [ ] Testing Strategy frontier is empty — what to test and how is defined
+- [ ] `assumptions` in frontmatter is non-empty
+- [ ] Every significant decision has a TDR (at minimum: stack, architecture pattern, storage)
+- [ ] Technical Adversarial Review completed — no unresolved Minimalist/Operator/Future Developer concerns
+- [ ] Riskiest decision identified with validation plan
+- [ ] Every decision has a recommended answer that was accepted, modified, or rejected
+
+A CLI tool might only need Stack + Architecture + Testing. A web app might need all areas.
 
 ---
 
-## Generate TECHNICAL.md
+## Generate docs/TECHNICAL.md
 
-Write to `TECHNICAL.md` in the project root.
+Write to `docs/TECHNICAL.md`. Create the `docs/` directory if it doesn't exist.
 
 **Frontmatter:**
 ```yaml
 ---
 status: complete
-areasExplored: [stack, architecture, data, interfaces, constraints]  # only what was explored
+areasExplored:
+  stack: { depth: N, decisions: N }
+  architecture: { depth: N, decisions: N }
+  # ... only areas that were actually explored
+assumptions:
+  - "{{assumption_1}}"
+riskiestDecision: "{{decision_title}} — validate by: {{method}}"
 generatedBy: know-thy-build
 version: 1.0.0
 date: {{date}}
@@ -212,6 +573,7 @@ date: {{date}}
 **Rules:**
 - Only include content from the conversation. No generic filler.
 - Preserve the user's reasoning — the *why* behind each choice matters.
+- **Include TDRs for significant decisions.** Each must have alternatives, rationale, consequences, and validation method.
 - **Omit sections that weren't discussed.**
 - The entire document MUST be written in {{LANG}}.
 
@@ -236,25 +598,39 @@ date: {{date}}
 **Dev Tools:**
 - {{tool}} — {{purpose}}
 
+**Weakest Link:** {{which choice is most likely to change and why}}
+
 ## Architecture
 
-<!-- Component structure as natural prose or simple list -->
+<!-- Component structure with responsibilities and boundaries -->
 
 {{architecture_pattern}}
 
-**Components:**
-- {{component}} — {{responsibility}}
+**Component Responsibility Map:**
+
+| Component | Responsibility | NOT Responsible For | Depends On |
+|-----------|---------------|---------------------|------------|
+| {{component}} | {{what it does}} | {{what it doesn't do}} | {{dependencies}} |
+
+**Data Flow:**
+<!-- Trace one request end-to-end through the components -->
+{{data_flow_trace}}
 
 **Interactions:**
 <!-- How components communicate -->
 
 ## Data
 
-**Storage:** {{storage}}
+**Storage:** {{storage}} — {{why_storage}}
 
 **Key Entities:**
 - {{entity}} — {{description}}
 
+**Relationships:**
+<!-- How entities relate to each other -->
+
+**Data Lifecycle:** {{data_lifecycle}}
+
 **Formats:** {{data_format}}
 
 ## Interfaces
@@ -263,9 +639,36 @@ date: {{date}}
 
 {{interfaces}}
 
+**Error Format:**
+<!-- Consistent error response structure -->
+{{error_format}}
+
 **External Dependencies:**
 - {{external_dep}} — {{purpose}}
 
+**Versioning:** {{versioning}}
+
+## Testing Strategy
+
+| Level | Scope | Tool | Rationale |
+|-------|-------|------|-----------|
+| {{unit/integration/e2e}} | {{what's tested at this level}} | {{tool}} | {{why this level matters}} |
+
+**Coverage Principle:** {{coverage_principle}}
+
+**What NOT to Test:** {{test_exclusions — glue code, framework internals, etc.}}
+
+## Error & Resilience
+
+<!-- Omit if not discussed. -->
+
+**Failure Modes:**
+- {{failure_mode}} — response: {{how the system handles it}}
+
+**Error Propagation:** {{error_propagation}}
+
+**Observability:** {{observability}}
+
 ## Constraints
 
 **Performance:** {{performance}}
@@ -273,6 +676,42 @@ date: {{date}}
 **Deployment:** {{deployment}}
 **Platforms:** {{platforms}}
 
+## Key Decisions
+
+<!-- Technical Decision Records for the most consequential choices.
+     Each entry: context, options, decision, rationale, consequences, validation. -->
+
+### {{decision_title}}
+
+**Context:** {{why this decision was needed}}
+
+| Option | Pros | Cons |
+|--------|------|------|
+| {{option_A}} | {{pros}} | {{cons}} |
+| {{option_B}} | {{pros}} | {{cons}} |
+
+**Decision:** {{chosen option}}
+**Why:** {{rationale — tied to PROJECT.md constraints}}
+**Consequences:** {{what this enables and prevents}}
+**Validation:** {{how to verify this was right}}
+
+<!-- Repeat for each significant decision -->
+
+## Risk Register
+
+<!-- The technical decision most likely to be wrong, and the fallback plan. -->
+
+**Riskiest Decision:** {{decision_title}}
+- **Why risky:** {{what makes reversal expensive}}
+- **Validate by:** {{method and timing}}
+- **Fallback:** {{what to pivot to if wrong}}
+
+## Assumptions
+
+<!-- Beliefs surfaced during technical exploration that haven't been validated. -->
+
+- {{assumption}} — if wrong: {{impact}}
+
 ---
 
 *Generated by know-thy-build | {{date}}*
@@ -287,8 +726,9 @@ When TECHNICAL.md has `status: complete` and the user indicates something has ch
 Follow the same evolve pattern as project:
 
 1. **What changed?** — follow the thread with iterative deepening
-2. **Was the original decision wrong, or did context change?** — important to distinguish
-3. **Apply changes** — Edit tool, preserve structure, update frontmatter
+2. **Was the original decision wrong, or did context change?** — important to distinguish. Check the TDR: does the original rationale still hold? Did the consequences play out as expected?
+3. **Review the Risk Register** — did the riskiest decision prove out? Update the risk assessment.
+4. **Apply changes** — Edit tool, preserve structure, update frontmatter
 
 **Update frontmatter:**
 ```yaml
@@ -309,6 +749,9 @@ lastEvolve: {{date}}
 
 **Why:**
 - {{what_triggered_the_change}}
+
+**TDR updated:**
+- {{which decision record was revised and how}}
 ```
 
 ---
@@ -316,11 +759,14 @@ lastEvolve: {{date}}
 ## Closing
 
 **After CREATE:**
-- TECHNICAL.md has been generated.
+- `docs/TECHNICAL.md` has been generated.
 - This defines the technical foundation for all implementation work.
+- **Next step:** Run `/know-thy-build:qa` to set up the QA framework (`docs/QA.md`) — it uses the deployment info from TECHNICAL.md to verify the test environment.
 - Feature specs (`/know-thy-build:feature`) will reference this automatically.
+- When implementing features, `/know-thy-build:architect` will work within these decisions.
 - Run `/know-thy-build:technical` again when technical direction shifts.
 
 **After EVOLVE:**
-- TECHNICAL.md has been updated with changelog.
+- `docs/TECHNICAL.md` has been updated with changelog.
 - Review if existing features need adjustment based on technical changes.
+- If a Key Decision changed, check if any `/know-thy-build:architect` scaffolds need revision.