warp-os 1.1.2 → 1.2.1

package/dist/warp-annotate/SKILL.md

@@ -0,0 +1,404 @@
+---
+name: warp-annotate
+description: >
+  Reconcile CLAUDE.md files with actual project state. Queries claude-mem for
+  recent observations and decisions, diffs against what CLAUDE.md files currently
+  say, and updates them. Reads everything, writes only CLAUDE.md files.
+triggers:
+  - /warp-annotate
+  - /annotate
+position: meta
+prev: null
+next: null
+pipeline_reads: []
+pipeline_writes: []
+---
+
+<!-- ═══════════════════════════════════════════════════════════ -->
+<!-- TIER 1 — Engineering Foundation. Generated by build.sh    -->
+<!-- ═══════════════════════════════════════════════════════════ -->
+
+
+# Warp Engineering Foundation
+
+Universal principles for every agent in the Warp pipeline. Tier 1: highest authority.
+
+---
+
+## Core Principles
+
+**Clarity over cleverness.** Optimize for "I can understand this in six months."
+
+**Explicit contracts between layers.** Modules communicate through defined interfaces. Swap persistence without touching the service layer.
+
+**Every component earns its place.** No speculative code. If a feature isn't in the current or next phase, it doesn't exist in code.
+
+**Fail loud, recover gracefully.** Never swallow errors silently. User-facing experience degrades gracefully — stale-data indicator, not a crash.
+
+**Prefer reversible decisions.** When two approaches are equivalent, choose the one that can be undone.
+
+**Security is structural.** Designed for the most restrictive phase, enforced from the earliest.
+
+**AI is a tool, not an authority.** AI agents accelerate development but do not make architectural decisions autonomously. Every significant design decision is reviewed by the user before it ships.
+
+---
+
+## Bias Classification
+
+When the same AI system writes code, writes tests, and evaluates its own output, shared biases create blind spots.
+
+| Level | Definition | Trust |
+|-------|-----------|-------|
+| **L1** | Deterministic. Binary pass/fail. Zero AI judgment. | Highest |
+| **L2** | AI interpretation anchored to verifiable external source. | Medium |
+| **L3** | AI evaluating AI. Both sides share training biases. | Lowest |
+
+**L1 Imperative:** Every quality gate that CAN be L1 MUST be L1. L3 is the outer layer, never the only layer. When L1 is unavailable, use L2 (grounded in external docs). Fall back to L3 only when no external anchor exists.
+
+---
+
+## Completeness
+
+AI compresses implementation 10-100x. Always choose the complete option. Full coverage, hardened behavior, robust edge cases. The delta between "good enough" and "complete" is minutes, not days.
+
+Never recommend the less-complete option. Never skip edge cases. Never defer what can be done now.
+
+---
+
+## Quality Gates
+
+**Hard Gate** — blocks progression. Between major phases. Present output, ask the user: A) Approve, B) Revise, C) Restart. MUST get user input.
+
+**Soft Gate** — warns but allows. Between minor steps. Proceed if quality criteria met; warn and get input if not.
+
+**Completeness Gate** — final check before artifact write. Verify no empty sections, key decisions explicit. Fix before writing.
+
+---
+
+## Escalation
+
+Always OK to stop and escalate. Bad work is worse than no work.
+
+**STOP if:** 3 failed attempts at the same problem, uncertain about security-sensitive changes, scope exceeds what you can verify, or a decision requires domain knowledge you don't have.
+
+---
+
+## External Data Gate
+
+When a task requires real-world data or domain knowledge that cannot be derived from code, docs, or git history — PAUSE and ask the user. Never hallucinate fixtures or APIs. Check docs via Context7 or saved files before writing code that touches external services.
+
+---
+
+## Error Severity
+
+| Tier | Definition | Response |
+|------|-----------|----------|
+| T1 | Normal variance (cache miss, retry succeeded) | Log, no action |
+| T2 | Degraded capability (stale data served, fallback active) | Log, degrade visibly |
+| T3 | Operation failed (invalid input, auth rejected) | Log, return error, continue |
+| T4 | Subsystem non-functional (DB unreachable, corrupt state) | Log, halt subsystem, alert |
+
+---
+
+## Universal Engineering Principles
+
+- Assert outcomes, not implementation. Test "input produces output" — not "function X calls Y."
+- Each test is independent. No shared state or execution order dependencies.
+- Mock at the system boundary, not internal helpers.
+- Expected values are hardcoded from the spec, never recalculated using production logic.
+- Every bug fix ships with a regression test.
+- Every error has two audiences: the system (full diagnostics) and the consumer (only actionable info). Never the same message.
+- Errors change shape at every module boundary. No error propagates without translation.
+- Errors never reveal system internals to consumers. No stack traces, file paths, or queries in responses.
+- Graceful degradation: live data → cached → static fallback → feature unavailable.
+- Every input is hostile until validated.
+- Default deny. Any permission not explicitly granted is denied.
+- Secrets never logged, never in error messages, never in responses, never committed.
+- Dependencies flow downward only. Never import from a layer above.
+- Each external service has exactly one integration module that owns its boundary.
+- Data crosses boundaries as plain values. Never pass ORM instances or SDK types between layers.
+- ASCII diagrams for data flow, state machines, and architecture. Use box-drawing characters (─│┌┐└┘├┤┬┴┼) and arrows (→←↑↓).
+
+---
+
+## Shell Execution
+
+Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`) or backslash paths in Bash tool calls. On Windows, use forward slashes, `ls`, `grep`, `rm`, `cat`.
+
+---
+
+## AskUserQuestion
+
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
+**Contract:**
+1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
+2. **Simplify:** Plain English a smart 16-year-old could follow.
+3. **Recommend:** Name the recommended option and why.
+4. **Options:** Ordered by completeness descending.
+5. **One decision per question.**
+
+**When to ask (mandatory):**
+1. Design/UX choice not resolved in artifacts
+2. Trade-off with more than one viable option
+3. Before writing to files outside .warp/
+4. Deviating from architecture or design spec
+5. Skipping or deferring an acceptance criterion
+6. Before any destructive or irreversible action
+7. Ambiguous or underspecified requirement
+8. Choosing between competing library/tool options
+
+**Completeness scores in labels (mandatory):**
+Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
+Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
+
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
+**Formatting:**
+- *Italics* for emphasis, not **bold** (bold for headers only).
+- After each answer: `✔ Decision {N} recorded`
+- Previews under 8 lines. Full mockups go in conversation text before the question.
+
+---
+
+## Scale Detection
+
+- **Feature:** One capability/screen/endpoint. Lean phases, fewer questions.
+- **Module:** A package or subsystem. Full depth, multiple concerns.
+- **System:** Whole product or greenfield. Maximum depth, every edge case.
+
+Detection: Single behavior change → feature. 3+ files → module. Cross-package → system.
+
+---
+
+## Artifact I/O
+
+Header: `<!-- Pipeline: {skill-name} | {date} | Scale: {scale} | Inputs: {prerequisites} -->`
+
+Validation: all schema sections present, no empty sections, key decisions explicit.
+Preview: show first 8-10 lines + total line count before writing.
+HTML preview: use `_warp_html.sh` if available. Open in browser at hard gates only.
+
+---
+
+## Completion Banner
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WARP │ {skill-name} │ {STATUS}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Wrote:      {artifact path(s)}
+Decisions:  {N} recorded
+Next:       /{next-skill}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Status values: **DONE**, **DONE_WITH_CONCERNS** (list concerns), **BLOCKED** (state blocker + what was tried + next steps), **NEEDS_CONTEXT** (state exactly what's needed).
+
+<!-- ═══════════════════════════════════════════════════════════ -->
+<!-- Skill-Specific Content.                                   -->
+<!-- ═══════════════════════════════════════════════════════════ -->
+
+
+# Annotate
+
+Lightweight reconciliation skill. Reads the world, writes only CLAUDE.md files.
+
+CLAUDE.md is the primary context document for every Claude Code session. When it drifts from reality, every session starts with wrong assumptions. This skill closes that gap.
+
+---
+
+## WHAT THIS SKILL DOES
+
+1. Reads all project-level CLAUDE.md files
+2. Identifies directories that *should* have a CLAUDE.md but don't
+3. Queries claude-mem for recent observations, decisions, and patterns
+4. Reads actual project state (file tree, configs, git history)
+5. Identifies drift, gaps, and stale references
+6. Updates existing CLAUDE.md files with accurate, contextual content
+7. Creates new CLAUDE.md files where coverage is missing
+
+**Writes ONLY to CLAUDE.md files. All other files are read-only.**
+
+---
+
+## STEP 1: Discover and Assess Coverage
+
+### 1A. Find existing CLAUDE.md files
+
+```bash
+find . -name "CLAUDE.md" -not -path "./.warp/*" -not -path "./node_modules/*" 2>/dev/null
+```
+
+Read each one fully — you need to know what they currently claim.
+
+### 1B. Identify missing CLAUDE.md files
+
+Scan the project for directories that represent a distinct domain — a module, layer, or subsystem with its own concerns — but lack a CLAUDE.md.
+
+Signs a directory warrants its own CLAUDE.md:
+- Contains 5+ source files with a shared purpose
+- Represents a distinct architectural layer (API, UI, data, hooks, etc.)
+- Has non-obvious conventions or patterns a new session should know
+- Is a frequent edit target (high git churn)
+
+Signs it does NOT need one:
+- Leaf directory with 1-2 files (the parent's CLAUDE.md covers it)
+- Generated directory (dist/, build/, node_modules/)
+- Contains only config files with no domain logic
+
+```bash
+# Directories with 5+ files, no CLAUDE.md
+find . -type d -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.warp/*" -not -path "./dist/*" | while read dir; do
+  count=$(find "$dir" -maxdepth 1 -type f | wc -l)
+  has_claude=$([ -f "$dir/CLAUDE.md" ] && echo "yes" || echo "no")
+  [ "$count" -ge 5 ] && [ "$has_claude" = "no" ] && echo "$dir ($count files)"
+done
+```
+
+For each candidate, decide: does a new session need domain-specific context about this directory that the root CLAUDE.md doesn't cover? If yes, flag it for creation in Step 4.
+
+---
+
+## STEP 2: Gather Context
+
+Three sources of truth, queried in parallel:
+
+### 2A. Claude-mem observations
+
+Query claude-mem MCP tools for recent context:
+
+- **Timeline** — what happened in recent sessions (file changes, decisions, architectural shifts)
+- **Search** — look for observations about architecture, new files, patterns, decisions
+- **Key queries:** "architectural decision", "new file", "renamed", "deleted", "refactored", "added dependency", "changed pattern"
+
+This gives you the *why* behind changes — not just what changed, but the reasoning and decisions that drove it.
+
+### 2B. Project state
+
+Read the actual project to understand what exists *right now*:
+
+```bash
+# Directory structure (top 3 levels)
+find . -type d -maxdepth 3 -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.warp/*" | sort
+
+# Key config files
+ls -la package.json tsconfig.json *.config.* .env.example Dockerfile Makefile 2>/dev/null
+
+# Recent git activity (files changed in last 20 commits)
+git log --oneline --name-only -20 | grep -v '^[a-f0-9]' | sort -u
+```
+
+### 2C. Git diff since last CLAUDE.md update
+
+```bash
+# When was each CLAUDE.md last modified?
+git log -1 --format="%H %ai" -- CLAUDE.md 2>/dev/null
+
+# What changed since then?
+git diff <last-claude-md-commit>..HEAD --stat 2>/dev/null
+```
+
+If CLAUDE.md has never been committed or is gitignored, compare against the file's filesystem mtime and recent git history.
+
+---
+
+## STEP 3: Identify Discrepancies
+
+Compare what CLAUDE.md says against what's actually true. Check each of these:
+
+**Structure claims:**
+- Directory tree in CLAUDE.md vs actual directory tree
+- File counts (skills, hooks, tests, etc.) vs actual counts
+- File references — do referenced files still exist?
+
+**Architectural claims:**
+- Patterns described vs patterns actually in code
+- Dependencies listed vs actual package.json / imports
+- Integration points described vs actual integrations
+
+**Status claims:**
+- Version numbers vs actual VERSION file
+- "Current status" section vs reality
+- Feature descriptions vs what's actually built
+
+**Missing content:**
+- New directories or files not mentioned anywhere
+- New architectural patterns (from claude-mem) not documented
+- New dependencies or integrations not listed
+- Decisions made (from claude-mem) that should inform the next session
+
+---
+
+## STEP 4: Draft Updates
+
+For each existing CLAUDE.md file, draft the specific changes needed. Group by type:
+
+- **Fix** — something CLAUDE.md says that's wrong (stale count, deleted file reference, old pattern)
+- **Add** — something that should be in CLAUDE.md but isn't (new directory, new pattern, new decision)
+- **Remove** — something in CLAUDE.md that no longer applies (deleted feature, removed dependency)
+
+For each new CLAUDE.md to create, draft the content:
+
+- **Header** — what this directory/module is and its role in the project
+- **Key files** — the important files and what they do (not every file — just the ones a new session needs to know about)
+- **Conventions** — non-obvious patterns, naming conventions, or rules specific to this domain
+- **Relationships** — how this module connects to others (what it imports from, what depends on it)
+
+Use claude-mem context to write entries that explain *why*, not just *what*:
+- Good: "Dual-path artifact lookup — identity-briefing.sh checks `.warp/reports/planning/` first, falls back to `.warp/pipeline/` for backwards compatibility with pre-restructure projects"
+- Bad: "identity-briefing.sh updated"
+
+Present a summary of proposed changes before writing:
+
+```
+CLAUDE.MD RECONCILIATION:
+  Update:
+    [path/to/CLAUDE.md]
+      Fix:  [N] items (stale references, wrong counts)
+      Add:  [N] items (new patterns, missing files)
+      Remove: [N] items (deleted features)
+
+  Create:
+    [path/to/new/CLAUDE.md] — [why this directory needs one]
+```
+
+---
+
+## STEP 5: Write Updates
+
+Apply the changes to each CLAUDE.md file using Edit. Preserve the existing structure and voice of each file — annotate updates sections in place, it doesn't rewrite from scratch.
+
+After writing, confirm:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WARP │ annotate │ DONE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Updated:  [list of CLAUDE.md files touched]
+  Fixed:    [N] stale references
+  Added:    [N] new entries
+  Removed:  [N] obsolete entries
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## MUST
+
+- Query claude-mem before making changes — observations provide context that makes updates meaningful, not mechanical.
+- Preserve the voice and structure of each CLAUDE.md — update in place, don't rewrite.
+- Explain *why* in new entries, not just *what* — use claude-mem decision context.
+- Show proposed changes before writing — no silent CLAUDE.md modifications.
+
+## MUST NOT
+
+- Write to any file other than CLAUDE.md files. Every other file is read-only.
+- Rewrite existing CLAUDE.md from scratch. Update sections in place.
+- Add speculative content. Only document what actually exists or was actually decided.
+- Remove content without evidence it's stale. If unsure, leave it and flag it.
+- Create CLAUDE.md in generated or ephemeral directories (dist/, node_modules/, .warp/, build/).

package/dist/warp-browse/SKILL.md

@@ -131,6 +131,8 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 
 ## AskUserQuestion
 
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
 **Contract:**
 1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
 2. **Simplify:** Plain English a smart 16-year-old could follow.
@@ -152,9 +154,15 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
 Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
 
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
 **Formatting:**
 - *Italics* for emphasis, not **bold** (bold for headers only).
-- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- After each answer: `✔ Decision {N} recorded`
 - Previews under 8 lines. Full mockups go in conversation text before the question.
 
 ---

package/dist/warp-build-code/SKILL.md

@@ -136,6 +136,8 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 
 ## AskUserQuestion
 
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
 **Contract:**
 1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
 2. **Simplify:** Plain English a smart 16-year-old could follow.
@@ -157,9 +159,15 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
 Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
 
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
 **Formatting:**
 - *Italics* for emphasis, not **bold** (bold for headers only).
-- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- After each answer: `✔ Decision {N} recorded`
 - Previews under 8 lines. Full mockups go in conversation text before the question.
 
 ---

package/dist/warp-orchestrator/SKILL.md

@@ -132,6 +132,8 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 
 ## AskUserQuestion
 
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
 **Contract:**
 1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
 2. **Simplify:** Plain English a smart 16-year-old could follow.
@@ -153,9 +155,15 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
 Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
 
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
 **Formatting:**
 - *Italics* for emphasis, not **bold** (bold for headers only).
-- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- After each answer: `✔ Decision {N} recorded`
 - Previews under 8 lines. Full mockups go in conversation text before the question.
 
 ---
@@ -516,6 +524,7 @@ The orchestrator is a loop, not a one-shot. It persists across the full pipeline
 6. **Respect the routing table.** Don't skip pipeline steps unless the user explicitly requests it.
 7. **Report execution mode clearly.** The user should always know whether a skill is dispatched or running directly, and why.
 8. **When running direct, load the skill's Tier 2 content.** Read the skill source file to get the cognitive patterns, phases, and calibration examples. Without Tier 2, you're improvising — not running the skill.
+9. **Cap every multi-option decision with AskUserQuestion.** During direct skill execution, any design, architecture, or approach choice with 2+ viable options MUST use AskUserQuestion — even mid-skill. Present your analysis and reasoning as conversational text first, then formalize the decision with the tool. Never leave options as prose without the tool.
 
 ## MUST NOT
 

package/dist/warp-plan-architect/SKILL.md

@@ -133,6 +133,8 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 
 ## AskUserQuestion
 
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
 **Contract:**
 1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
 2. **Simplify:** Plain English a smart 16-year-old could follow.
@@ -154,9 +156,15 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
 Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
 
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
 **Formatting:**
 - *Italics* for emphasis, not **bold** (bold for headers only).
-- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- After each answer: `✔ Decision {N} recorded`
 - Previews under 8 lines. Full mockups go in conversation text before the question.
 
 ---
@@ -257,6 +265,28 @@ Internalize these cognitive patterns. They fire simultaneously on every input yo
 
 ---
 
+## PHASE 0: Scope Challenge
+
+**Goal:** Before starting architecture, challenge whether the scope is right-sized. Architecture amplifies scope — if the scope is too large, the architecture will be too large. Five minutes here saves five days in build.
+
+Read `.warp/reports/planning/scope.md` and the codebase. Then produce:
+
+```
+SCOPE CHALLENGE:
+  Existing code that solves sub-problems: [search codebase for partial solutions]
+  Minimum change set: [what is the smallest change that delivers the scope?]
+  Complexity smell: [>8 files or >2 new classes/services = smell — justify or simplify]
+  Built-in alternatives: [does the framework/language have this built in?]
+  TODOS cross-reference: [does TODOS.md already track related work?]
+  Completeness check: [AI compresses cost — always prefer the complete version]
+```
+
+If the scope challenge reveals the work is simpler than planned — existing code already solves sub-problems, the framework has built-in support, or the minimum change set is smaller than expected — surface it via AskUserQuestion and suggest scope reduction before proceeding. Do not architect a system larger than the problem requires.
+
+If the scope holds, proceed to Phase 1.
+
+---
+
 ## PHASE 1: System Audit
 
 **Goal:** Understand what exists before designing what to build. New architecture on top of unexamined existing architecture produces collisions.
@@ -380,6 +410,25 @@ OPERATION: [name, e.g., "fetch pilot's active flight"]
 
 [SYSTEM scale] Produce this for every primary operation. [MODULE scale] Produce this for the 3 most complex operations. [FEATURE scale] Produce this for the primary operation only.
 
+### 2D. Error & Rescue Map
+
+For each major operation documented in 2C, produce a rescue map that pairs every failure with a specific recovery action and user-visible outcome. This complements the four-path data flow by mapping the operational response plan:
+
+```
+ERROR & RESCUE MAP:
+  ┌──────────────────┬─────────────────┬──────────────────┬────────────────────┐
+  │ Method/Codepath   │ What Can Fail    │ Rescue Action     │ User-Visible Result │
+  ├──────────────────┼─────────────────┼──────────────────┼────────────────────┤
+  │ [specific method] │ [specific error] │ [specific action]  │ [specific outcome]  │
+  └──────────────────┴─────────────────┴──────────────────┴────────────────────┘
+```
+
+Rules:
+- Every row must name a specific method or codepath, not a vague category.
+- "Rescue Action" must be actionable: retry with backoff, return cached value, degrade gracefully, alert on-call. Never "handle error."
+- "User-Visible Result" must describe exactly what the user sees or experiences. Never "an error message."
+- If a method can fail in multiple ways, each failure gets its own row.
+
 ---
 
 ## PHASE 3: API Design
@@ -547,6 +596,34 @@ BOUNDARY: [Component A] → [Component B]
 
 ---
 
+## PHASE 4.6: Observability & Debuggability Review
+
+**Goal:** Verify that every major component can be diagnosed in production without attaching a debugger. Systems without observability are systems that fail silently and stay broken longer.
+
+For each major component defined in Phase 2, produce:
+
+```
+OBSERVABILITY:
+  Logging: [what is logged? structured? levels correct?]
+  Metrics: [key metrics exposed? latency, error rate, throughput?]
+  Tracing: [distributed tracing support? correlation IDs?]
+  Alerting: [what triggers alerts? who gets paged?]
+  Debuggability: [can you diagnose issues from logs alone?]
+  Admin tooling: [any admin endpoints or tools needed?]
+```
+
+Rules:
+- **Logging:** Every component must log at structured format (JSON or equivalent). Log levels must be correct: ERROR for things that break, WARN for things that degrade, INFO for state transitions, DEBUG for investigation. If a component has no logging plan, flag it.
+- **Metrics:** At minimum, every component that handles requests must expose latency (p50/p95/p99), error rate, and throughput. Components that manage queues must expose queue depth and processing lag.
+- **Tracing:** If the system has more than two components in a request path, correlation IDs are required. Every log line in a request must include the correlation ID so the full path can be reconstructed.
+- **Alerting:** Every failure mode from Phase 4 must have a corresponding alert or explicit justification for why it does not need one. "We will notice" is not an alerting strategy.
+- **Debuggability:** The litmus test: can an engineer who did not build this component diagnose a production issue using only logs, metrics, and traces — without reading the source code? If not, the observability is insufficient.
+- **Admin tooling:** If the system requires manual intervention for any operational task (clearing a stuck queue, resetting a user's state, force-refreshing cached data), document the admin tool or endpoint that enables it.
+
+[FEATURE scale] Brief format — logging and key metrics only. [MODULE scale] Full format for each component. [SYSTEM scale] Full format plus cross-component tracing architecture.
+
+---
+
 ## PHASE 5: Technical Decisions
 
 **Goal:** Document each significant technical choice with rationale and alternatives. Future engineers need to understand why, not just what.
@@ -584,6 +661,39 @@ Categories that almost always contain significant decisions:
 
 **Goal:** Write the architecture artifact that design, spec, and build all depend on.
 
+### 6A. Unresolved Decision Tracking
+
+Before writing, review all AskUserQuestion interactions from Phases 0-5. List any decisions the user did not fully answer, deferred, or gave ambiguous responses to:
+
+```
+UNRESOLVED DECISIONS:
+  - [decision description] — deferred because: [reason] — revisit when: [trigger]
+```
+
+Include these in architecture.md under a "## Unresolved Decisions" section. These are not failures — they are explicitly tracked unknowns. Downstream skills (design, build) must check this section and either resolve the decision when they have more context or carry it forward.
+
+### 6B. Worktree Parallelization Strategy (Optional)
+
+If the architecture has >3 independent components that could be built concurrently (no shared data models, no blocking dependencies), produce a parallelization strategy. This enables the build phase to use git worktrees for concurrent implementation:
+
+```
+PARALLELIZATION STRATEGY:
+  ┌──────────────┬──────────────────┬──────────────┬───────────────┐
+  │ Lane          │ Components        │ Dependencies  │ Can Start After│
+  ├──────────────┼──────────────────┼──────────────┼───────────────┤
+  │ Lane A       │ [component list]  │ none          │ immediately    │
+  │ Lane B       │ [component list]  │ Lane A types  │ Lane A types   │
+  └──────────────┴──────────────────┴──────────────┴───────────────┘
+```
+
+Rules:
+- A lane is a set of components that can be built independently by a separate agent in a worktree.
+- Lane dependencies must be explicit: "Lane B needs the type definitions from Lane A" — not "Lane B needs Lane A to be done."
+- Shared types/interfaces should be in their own lane (often Lane A) so other lanes can start as soon as types are defined.
+- If no meaningful parallelization exists (everything depends on everything else), skip this section.
+
+### 6C. Completeness Gate
+
 Run a completeness gate before writing:
 
 1. Every component in scope has a defined boundary and responsibility
@@ -633,6 +743,15 @@ Create `.warp/reports/planning/architecture.md`:
 ## Technical Decisions
 {Each decision with context, options, choice, rationale, reversibility}
 
+## Observability
+{Per component: logging, metrics, tracing, alerting, debuggability, admin tooling}
+
+## Unresolved Decisions
+{Decisions deferred or unanswered during architecture — description, reason, revisit trigger}
+
+## Parallelization Strategy
+{If applicable: lanes, components per lane, dependencies, start conditions}
+
 ## Open Questions for Design
 {Unresolved questions that the design phase must answer}