pan-wizard 2.8.1 → 2.9.1

package/commands/pan/focus-design.md

@@ -41,9 +41,74 @@ If you find yourself analyzing PAN command files, agent definitions, or `pan-too
 
 ---
 
-## MANDATORY: Complete All Phases For Selected Mode
+## Tool Selection Priority
 
-When `/pan:focus-design` is invoked, execute ALL phases for the selected mode automatically. Do NOT stop to ask questions between phases. Do NOT skip phases beyond what the mode specifies. Complete the FULL investigation and produce all output artifacts. The only permitted pause is the Strategy Gate in Phase 3 (if the user passed `--gate`).
+Use the simplest sufficient tool for each research operation:
+1. **Grep/Glob** — for finding patterns and files in the local codebase
+2. **Read** — for examining specific files identified by Grep/Glob
+3. **Bash** — for git history, test runs, build commands
+4. **Agent (subagent)** — for broad exploration spanning many files (>5 reads)
+5. **WebSearch/WebFetch** — for external research after local sources are exhausted
+6. **mcp__context7__*** — for library documentation lookups
+
+Prefer local evidence over web research. Start with the codebase, then broaden.
+
+## Context Management Across Phases
+
+This pipeline spans 10+ phases. Manage context to maintain quality:
+- **KEEP:** Problem statement, success criteria, key architectural decisions, file paths being designed for
+- **SUMMARIZE:** Research findings (compress to key takeaways after each research phase), competitive analysis results
+- **DISCARD:** Raw web fetch content after extracting relevant data, superseded design drafts
+- After Phase 3 (Strategic Analysis), summarize all findings from Phases 0-3 into a compact brief before entering design phases
+
+**Progressive context loading — load only what the current phase needs:**
+
+| Phase | What to Load | What NOT to Load Yet |
+|-------|-------------|---------------------|
+| 0. Problem | User's feature description, project README | Implementation details, test files |
+| 1. Landscape | Web search results, competitor docs | Project internals |
+| 2. Codebase | Relevant source files (Glob→Grep→Read) | Unrelated modules, full test suite |
+| 3. Strategic | Findings from 0-2 (summarized) | Raw web content (discard after summary) |
+| 4-6. Design | Architecture files, key modules, API surface | Test implementation details |
+| 7-8. Spec | Design decisions from 4-6, test patterns | Research raw data (long gone) |
+| 9. Output | Spec template, ADR template | Everything else (already in spec) |
+
+**Why:** A 10-phase pipeline that loads everything in Phase 0 exhausts context by Phase 5. Each phase loads only its inputs, summarizes its outputs, and discards its raw data.
+
+---
+
+## Reasoning Protocol
+
+For research and analysis phases (0, 1, 2, 3), follow observe-think-act:
+1. **OBSERVE** — State what you found (code patterns, competitive data, user needs)
+2. **THINK** — Reason about what this means for the design
+3. **ACT** — Record the finding and move to the next investigation step
+This keeps research structured and prevents rabbit holes.
+
+## Meta-Prompting: Self-Generated Investigation Strategy
+
+Before starting Phase 0, generate your own investigation plan based on the feature description:
+
+```
+Given: "{feature description}"
+My investigation strategy:
+1. What is the core problem? → {how I'll validate it}
+2. Who are the competitors? → {what to search for}
+3. What codebase areas are affected? → {what to Glob/Grep for}
+4. What are the likely architectural constraints? → {what to read}
+5. What risks should I watch for? → {security, performance, compatibility}
+6. What is the ideal output format? → {spec structure for this feature type}
+```
+
+This self-generated strategy adapts to the specific feature rather than following a generic checklist. A "add caching layer" feature needs different investigation than "add OAuth provider" — the meta-prompt captures that difference upfront.
+
+**After Phase 3, regenerate:** The strategy may need revision based on what you've learned. Update it before entering design phases.
+
+---
+
+## Complete All Phases For Selected Mode
+
+When `/pan:focus-design` is invoked, execute all phases for the selected mode automatically. Do not stop to ask questions between phases or skip phases beyond what the mode specifies. Complete the full investigation and produce all output artifacts. The only permitted pause is the Strategy Gate in Phase 3 (if the user passed `--gate`).
 
 **Modes (mutually exclusive — pick one, default `--full`):**
 
@@ -569,36 +634,255 @@ Every error condition must specify:
 
 ## Phase 5: Architecture Decision Record
 
-Create a formal ADR:
+> *An ADR is the institutional memory of WHY. Make it comprehensive enough that a developer joining 12 months from now can understand the full decision landscape without asking anyone.*
+
+### 5.0 ADR Numbering
+- Read existing ADRs in `docs/decisions/` to determine the next sequential number
+- Format: `ADR-NNNN-<kebab-case-feature-name>.md` (e.g., `ADR-0019-webhook-support.md`)
+
+### 5.1 ADR Structure (MANDATORY — all sections required)
+
+The ADR MUST contain ALL of the following sections. Do NOT produce a skeleton with placeholder text — every section must have substantive, project-specific content drawn from the preceding phases.
 
 ```markdown
-# ADR-NNNN: [Feature Name]
+# ADR-NNNN: [Descriptive Title — not just feature name but what was decided]
 
 ## Status
-Proposed
+Proposed | Accepted | Superseded by ADR-NNNN | Amended by ADR-NNNN
+
+## Date
+YYYY-MM-DD
 
 ## Context
-[Problem context — what forces are at play?]
+
+### Problem Statement
+[1-2 paragraphs: What problem exists? Why does it matter? What is the cost of inaction?
+Pull directly from Phase 0.1 — do not paraphrase into vague generalities.]
+
+### Forces & Constraints
+[Enumerate the specific technical, business, regulatory, and organizational forces
+that constrain the solution space. These come from Phase 0 + Phase 1 discoveries.]
+
+- **[Force 1]:** [Specific constraint and why it matters]
+- **[Force 2]:** [Specific constraint and why it matters]
+- **[Force 3]:** [Specific constraint and why it matters]
+
+### Current State
+[What exists today? Reference actual files, modules, endpoints discovered in Phase 0.8.
+If enhancing an existing feature, include the Before/After delta from Phase 0.2.5.]
+
+### Requirements Traceability
+[Map to the spec that triggered this ADR. List the success criteria from Phase 0.4.]
+
+| Requirement | Source | ADR Section |
+|-------------|--------|-------------|
+| [SC-1 from Phase 0.4] | [spec file or user request] | Decision §X |
+| [SC-2 from Phase 0.4] | [spec file or user request] | Decision §Y |
 
 ## Decision
-[What was decided and why]
+
+### Summary
+[1-2 sentences: The decision in plain language. A busy reader should understand
+the choice from this paragraph alone.]
+
+### Detailed Design Decisions
+[Number each sub-decision. For each, state WHAT was decided and WHY.
+Pull from Phase 4 design synthesis — every design choice documented there
+must appear here with rationale.]
+
+#### 1. [Sub-decision title]
+**Decided:** [What]
+**Rationale:** [Why — reference forces from Context, competitive findings from Phase 2,
+or architectural constraints from Phase 3.5]
+**Alternatives rejected:** [Brief — full analysis in Options Considered]
+
+#### 2. [Sub-decision title]
+**Decided:** [What]
+**Rationale:** [Why]
+**Alternatives rejected:** [Brief]
+
+[Continue for all significant decisions — typically 3-8 sub-decisions]
+
+### Architecture & Integration
+[How does this fit into the existing system? Include the dependency map from Phase 1.4
+and the layer violation check from Phase 3.5.2. Show which modules are touched.]
+
+```
+[Dependency diagram or integration flow from Phase 1.4 / 3.5.6]
+```
+
+### Interface Contract
+[The output schema or API contract from Phase 3.5.3 — exact format, not just description.
+Include request/response examples for APIs, CLI input/output for commands,
+or data schema for storage changes.]
 
 ## Consequences
+
 ### Positive
-- [Benefit 1]
+[Minimum 3 consequences. Each must be specific and measurable, not generic platitudes.
+BAD: "Better user experience" — GOOD: "Reduces statement processing failure rate
+from 80% to <5% for image-based uploads"]
+
+- **[Specific benefit 1]:** [Measurable impact]
+- **[Specific benefit 2]:** [Measurable impact]
+- **[Specific benefit 3]:** [Measurable impact]
+
 ### Negative
-- [Cost 1]
+[Minimum 2 consequences. Be honest about costs and tradeoffs.
+Every negative must include a mitigation strategy or explicit acceptance rationale.]
+
+- **[Specific cost 1]:** [Impact] — *Mitigation:* [how addressed or why accepted]
+- **[Specific cost 2]:** [Impact] — *Mitigation:* [how addressed or why accepted]
+
 ### Neutral
-- [Side effect]
+[Side effects that are neither clearly positive nor negative]
+
+- [Side effect 1]
+- [Side effect 2]
 
 ## Options Considered
-1. [Option A] — [summary]
-2. [Option B — chosen] — [summary]
 
-## Links
-- Related to: [commands, modules, issues]
+> *Document ALL options evaluated, including the chosen one. For each option,
+> provide enough detail that a reader can understand why it was accepted or rejected
+> WITHOUT reading the full spec.*
+
+### Option 1: [Name] — REJECTED
+**Description:** [2-3 sentences: what this approach involves]
+**Pros:** [Bullet list]
+**Cons:** [Bullet list]
+**Rejected because:** [Specific reason tied to forces/constraints in Context]
+
+### Option 2: [Name] — REJECTED
+**Description:** [2-3 sentences]
+**Pros:** [Bullet list]
+**Cons:** [Bullet list]
+**Rejected because:** [Specific reason]
+
+### Option 3: [Name] — CHOSEN
+**Description:** [2-3 sentences]
+**Pros:** [Bullet list]
+**Cons:** [Bullet list — same as Negative consequences]
+**Chosen because:** [Specific reason — ties back to forces, competitive position, strategic analysis]
+
+### Option 4: [Name] — DEFERRED
+**Description:** [2-3 sentences]
+**Deferred because:** [Not rejected — viable for future consideration. State trigger conditions.]
+
+[Include 3-5 options minimum. If fewer than 3 alternatives were genuinely considered,
+explain why the solution space was constrained.]
+
+### Decision Matrix (when 3+ options share comparable tradeoffs)
+| Criterion (from forces) | Weight | Option 1 | Option 2 | Option 3 (chosen) |
+|--------------------------|--------|----------|----------|-------------------|
+| [Force/requirement 1] | High | Poor | Good | Excellent |
+| [Force/requirement 2] | Medium | Good | Poor | Good |
+| [Force/requirement 3] | High | N/A | Good | Excellent |
+| **Weighted Score** | | Low | Medium | **High** |
+
+## Success Criteria
+
+[Copy directly from Phase 0.4 — these are the machine-checkable acceptance criteria
+that determine whether this ADR's decision was correctly implemented.]
+
+| ID | Criterion | Verification Method | Pass Condition |
+|----|-----------|-------------------|----------------|
+| SC-1 | [description] | test / grep / manual | [exact condition] |
+| SC-2 | [description] | test / grep / manual | [exact condition] |
+| SC-3 | No regression | project test command | All existing tests pass |
+
+## Breaking Changes
+
+[From Phase 3.5.5. If no breaking changes, state "None — all changes are additive."]
+
+| Change | Impact | Migration Strategy |
+|--------|--------|--------------------|
+| [What changes] | [Who is affected] | [How to migrate] |
+
+## Security Implications
+
+[From Phase 7. Summarize the threat model and key controls.]
+
+| Threat | Risk Level | Control |
+|--------|-----------|---------|
+| [Threat from STRIDE-lite] | Low/Medium/High | [Mitigation implemented] |
+
+If no security implications: "No new attack surface introduced. [Brief justification.]"
+
+## Performance Implications
+
+[From Phase 3.5.7 performance budget. State the expected performance characteristics
+and any budgets that must be maintained.]
+
+| Operation | Budget | Justification |
+|-----------|--------|---------------|
+| [Key operation 1] | < Xms | [Why this budget] |
+| [Key operation 2] | < Xms | [Why this budget] |
+
+## Implementation Guidance
+
+[From Phase 8. Not the full task list — just enough for an implementer to know
+WHERE to start and what patterns to follow.]
+
+| Order | Task | Files Affected | Effort |
+|-------|------|---------------|--------|
+| 1 | [First task] | [file paths] | XS/S/M/L |
+| 2 | [Second task] | [file paths] | XS/S/M/L |
+
+**Patterns to follow:** [Reference specific existing implementations discovered in Phase 0.8
+that the implementer should use as templates]
+
+## Feature Ladder
+
+[From Phase 4.5. Shows the incremental delivery plan.]
+
+| Version | Scope | Value Delivered |
+|---------|-------|----------------|
+| v0 (MVP) | [smallest useful slice] | [what user can do] |
+| v1 (Complete) | [full feature] | [full value] |
+| v2 (Enhanced) | [future extensions] | [additional value] |
+
+## Links & References
+
+- **Spec:** `docs/specs/<feature>_featureai.md`
+- **Related ADRs:** [list with brief relationship description]
+- **Supersedes:** [ADR number if replacing a previous decision, or "N/A"]
+- **External references:** [Standards, RFCs, competitor docs, regulatory requirements]
+- **Affected components:** [List of files/modules/services from impact analysis]
 ```
 
+### 5.2 ADR Quality Gate (Self-Check Before Writing)
+
+Before writing the ADR file, verify ALL of these:
+
+| Check | Requirement | Source Phase |
+|-------|-------------|-------------|
+| Context has specific forces | Not just "we need X" — enumerate WHY and WHAT CONSTRAINS | Phase 0 + 1 |
+| Decision has numbered sub-decisions | Every design choice from Phase 4 is captured with rationale | Phase 4 |
+| Options >= 3 | At least 3 genuine alternatives evaluated | Phase 2 + 3 |
+| Each option has pros AND cons | No straw-man options set up just to be rejected | Phase 2 + 3 |
+| Consequences are specific | No generic "better UX" — measurable impacts only | Phase 3 + 4 |
+| Negative consequences have mitigations | Every cost is either mitigated or explicitly accepted | Phase 4 |
+| Success criteria are machine-checkable | At least 2 can be verified by automated test | Phase 0.4 |
+| Breaking changes documented or "None" stated | Never omitted silently | Phase 3.5.5 |
+| Security section present | Even if "no new attack surface" — must be explicit | Phase 7 |
+| Performance budget stated | Key operations with time budgets | Phase 3.5.7 |
+| Implementation guidance references real files | Not hypothetical paths — actual discovered locations | Phase 0.8 + 8 |
+| Links trace to spec file | ADR → spec → requirements chain is complete | Phase 10 |
+
+**If any check fails:** Go back to the relevant phase and extract the missing content. Do NOT write placeholder text.
+
+### 5.3 ADR Anti-Patterns (NEVER DO)
+
+- **Skeleton ADR:** `[Problem context — what forces are at play?]` — NEVER use placeholder brackets in the output
+- **Single-option ADR:** Only describing the chosen approach without alternatives — this is a design doc, not an ADR
+- **Consequence-free ADR:** Listing only positives — EVERY decision has real costs
+- **Generic consequences:** "Improves code quality" / "Better maintainability" — be specific or remove
+- **Missing rationale:** "We chose X" without explaining WHY over alternatives
+- **Orphan ADR:** No link to spec, no link to related ADRs, no traceability
+- **Copy-paste from spec:** The ADR is a DECISION record, not a spec summary — focus on WHY, not WHAT
+- **Straw-man options:** Including obviously bad alternatives just to make the chosen option look good
+- **Missing migration strategy:** Documenting breaking changes without explaining how to handle them
+
 ---
 
 ## Phase 6: Error Handling & Diagnostics Design
@@ -753,6 +1037,10 @@ Write complete spec to: `docs/specs/<feature_name>_featureai.md`
 ### 10.2 Save ADR
 Write ADR to: `docs/decisions/ADR-NNNN-<feature_name>.md`
 
+**ADR completeness gate:** Before saving, verify the ADR passes ALL checks from Phase 5.2. The ADR file must contain every section defined in Phase 5.1 with substantive content — no placeholder brackets, no skeleton sections, no missing tables. If any section would be empty, go back to the relevant phase and extract the content.
+
+**Minimum ADR size:** A proper ADR for a `--full` mode investigation should be 80-200+ lines. If the ADR is under 60 lines, it is almost certainly missing required sections. For `--internal` mode, minimum 60 lines. For `--outward` mode, minimum 70 lines.
+
 ### 10.3 Report Summary
 Output a complete summary with:
 - **Problem & Evidence** — 1-sentence problem, evidence sources