@a-canary/pi-choose-wisely 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# Pi Choose Wisely
+
+A pi-package for architectural decision management using the CHOICES.md framework.
+
+## Installation
+
+```bash
+pi install git:github.com/a-canary/pi-choose-wisely
+# or
+pi install /path/to/pi-choose-wisely
+```
+
+## Skills
+
+### `/choose-wisely`
+
+Clarify project vision, mission, UX, operations, and architectural decisions in CHOICES.md.
+
+- Auto-bootstraps from existing docs if CHOICES.md missing
+- Validates with cascading impact review after changes
+- Runs structural audit automatically
+
+```
+/choose-wisely                              # Bootstrap or show status
+/choose-wisely add OAuth authentication     # Add a choice
+/choose-wisely change database to Postgres  # Modify a choice
+/choose-wisely audit                        # Full validation
+```
+
+### `/choose-wisely:replan`
+
+Gap analysis: compare CHOICES.md against current implementation state, generate PLAN.md for next phase.
+
+```
+/choose-wisely:replan                       # Analyze gaps, generate plan
+```
+
+## CHOICES.md Structure
+
+8 sections in priority order:
+
+| Section | Prefix | What goes here |
+|---------|--------|----------------|
+| Mission | M- | Why we exist, values, principles |
+| User Experiences | UX- | Core user journeys, interactions |
+| Features | F- | Specific capabilities |
+| Operations | O- | Automation, SLAs, workflows |
+| Data | D- | Storage decisions, schemas |
+| Architecture | A- | System design (tool-agnostic) |
+| Technology | T- | Tech stack, libraries (names tools) |
+| Implementation | I- | Dev practices, standards |
+
+## Choice Format
+
+```markdown
+### A-0012: Event-driven architecture for order processing
+Supports: F-0003, O-0002
+
+Use message queue for order events. Decouples billing, inventory,
+and shipping services. Enables async processing for traffic spikes.
+```
+
+**Rules:**
+- Position = Priority (higher constrains lower)
+- `Supports:` required on every choice (except top)
+- Architecture is tool-agnostic, Technology names tools
+
+## Helper Modules
+
+Loaded on-demand by the main skill:
+
+- `lib/bootstrap.md` — Scan docs, extract choices
+- `lib/audit.md` — 8 validation checks
+- `lib/cascade.md` — 3-check impact review
+- `lib/interview.md` — Planning questions by category
+
+## Templates
+
+- `templates/CHOICES.md` — Empty template with 8 sections
+- `templates/PLAN.md` — Phased implementation plan
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@a-canary/pi-choose-wisely",
+  "version": "1.0.0",
+  "description": "CHOICES.md management — clarify project vision, mission, UX, operations, architectural decisions with cascading impact review. Includes replan skill for gap analysis and PLAN.md generation.",
+  "keywords": ["pi-package"],
+  "author": {
+    "name": "a-canary"
+  },
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "skills": ["./skills"],
+    "templates": ["./templates"]
+  }
+}

package/skills/choose-wisely/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: choose-wisely
+description: "Clarify project vision, mission, UX, operations, and architectural decisions in CHOICES.md. Auto-bootstraps from existing docs, validates with cascading impact review."
+---
+
+# Choose Wisely — Architectural Decision Management
+
+Manage project choices in CHOICES.md. Auto-bootstraps if missing, runs cascading audit after changes.
+
+## Quick Routing
+
+| User Input | Action |
+|------------|--------|
+| No CHOICES.md | Bootstrap from template + existing docs |
+| "audit" / "check" | Run full validation, report issues |
+| "init" / "bootstrap" | Scan docs, extract choices |
+| Describing a change | Apply with 3-check cascade |
+| Empty/new project | Offer planning interview |
+
+## Workflow
+
+### 1. Discover
+
+Find CHOICES.md (project root, docs/, .pi/). If missing, create from template:
+
+```
+Template: {{SKILL_DIR}}/../templates/CHOICES.md
+Target: {{PROJECT_ROOT}}/CHOICES.md
+```
+
+### 2. Parse State
+
+If CHOICES.md exists, parse into:
+- Sections (Mission → Implementation)
+- Choices with ID, title, rationale
+- `Supports:` dependency graph
+
+### 3. Route by Input
+
+#### Bootstrap (no CHOICES.md or "init")
+
+Load [bootstrap module](lib/bootstrap.md) to scan existing docs:
+- README.md, ARCHITECTURE.md, DESIGN.md
+- docs/*.md, specs/*.md
+- ADR files
+
+Extract choices → assign IDs → write CHOICES.md.
+
+#### Audit ("audit" / "check")
+
+Load [audit module](lib/audit.md) and run 8 validation checks. Report issues tersely:
+
+> 23 choices audited. 1 stale reference in "timeout operations" choice. No gaps, no contradictions. Clean.
+
+#### Change (describing modification)
+
+Apply edit, then run [cascade module](lib/cascade.md):
+
+**Three checks per change:**
+1. **Upward**: Does change still support its `Supports:` targets?
+2. **Lateral**: Any contradictions/redundancies in same section?
+3. **Downward**: Do choices referencing this one still hold?
+
+Cascade silently to convergence. Summarize in 2-3 sentences by title.
+
+#### Planning (empty project / "plan")
+
+Load [interview module](lib/interview.md) and conduct structured interview:
+- Mission questions (why, who, value)
+- UX questions (workflow, interactions)
+- Architecture questions (patterns, communication)
+- Technology questions (frameworks, tools)
+
+Generate CHOICES.md with decisions + PLAN.md for next phase.
+
+### 4. Always Audit
+
+After any change, run audit checks. Only surface if issues found.
+
+### 5. Commit
+
+Commit CHOICES.md independently with descriptive message.
+
+## CHOICES.md Format
+
+```markdown
+### X-0001: Title of choice
+Supports: X-0000, Y-0000
+
+One to two lines of rationale. Not a spec.
+```
+
+**Sections (fixed order):**
+1. Mission (M-)
+2. User Experiences (UX-)
+3. Features (F-)
+4. Operations (O-)
+5. Data (D-)
+6. Architecture (A-)
+7. Technology (T-)
+8. Implementation (I-)
+
+**Rules:**
+- Position = Priority (higher constrains lower)
+- `Supports:` required on every choice except top
+- Architecture is tool-agnostic, Technology names tools
+
+## Modules
+
+- [lib/bootstrap.md](lib/bootstrap.md) — Scan docs, extract choices
+- [lib/audit.md](lib/audit.md) — 8 validation checks
+- [lib/cascade.md](lib/cascade.md) — 3-check impact review
+- [lib/interview.md](lib/interview.md) — Planning questions

package/skills/choose-wisely/lib/audit.md

@@ -0,0 +1,97 @@
+# Audit Module — CHOICES.md Validation
+
+Run 8 validation checks to ensure structural integrity and consistency.
+
+## Process
+
+Run checks iteratively — up to 10 passes. Apply fixes, re-run until convergence (zero new issues).
+
+## Checks (in order)
+
+### 1. Structural Integrity
+
+- [ ] Sections in correct order: Mission > UX > Features > Operations > Data > Architecture > Technology > Implementation
+- [ ] Each choice ID uses correct prefix for its section
+- [ ] IDs are globally unique (no duplicates)
+- [ ] Every choice (except top-most) has `Supports:` line
+- [ ] `Supports:` references only valid IDs that exist
+- [ ] `Supports:` only points upward (higher priority choices)
+
+### 2. Support Integrity
+
+For each choice:
+- [ ] Rationale connects to `Supports:` targets?
+- [ ] Orphaned choices flagged (no other choice references them)
+
+### 3. Standalone Comprehensibility
+
+**3a. Undefined terms**
+- Flag domain terms used in 3+ choices but not defined where first used
+
+**3b. Opaque names**
+- Flag module/component names without explanation
+
+**3c. Scope completeness**
+- Mission answers: content scope, audience, platform scope
+
+**3d. Dangling counts**
+- Flag numbers without traceable items ("9 data stores" → list them)
+
+### 4. Section Coherence
+
+Within each section:
+- [ ] No contradictions between choices
+- [ ] No redundancies (same decision stated twice)
+- [ ] Ordering is logical (constraining choices first)
+
+### 5. Architecture Tool-Agnosticism
+
+- [ ] Architecture section contains no named technologies
+- Architecture describes patterns, Technology names tools
+- If found, suggest move to Technology section
+
+### 6. Bottom-Up: Implicit Choices
+
+Look for patterns in lower sections (Data→Implementation):
+- [ ] Cluster choices with shared themes
+- [ ] Propose abstractions for clusters without explicit parent choice
+
+### 7. Top-Down: Implementation Gaps
+
+- [ ] Every choice in Mission→Operations appears in at least one `Supports:` line in Data→Implementation
+- Flag high-level choices without supporting implementation
+
+### 8. Cross-File (if applicable)
+
+- [ ] Parent choices correctly inherited
+- [ ] No contradictions with parent
+- [ ] No ID collisions
+
+## Auto-Fixes
+
+When issues found, offer to fix:
+
+| Issue | Auto-Fix |
+|-------|----------|
+| Missing `Supports:` | Suggest based on content |
+| Invalid reference | Remove or suggest correct ID |
+| Wrong section | Move to correct section |
+| Tech in Architecture | Move to Technology |
+| Duplicate ID | Renumber |
+
+## Output Format
+
+Run silently. When converged, report tersely:
+
+```
+Audit: 23 choices, converged in 2 passes.
+
+[✓] Structure valid
+[✓] Support chains intact
+[✓] No contradictions
+[~] 1 warning: "session timeout" choice references undefined term "JWT"
+
+Fixed: 1 stale reference in timeout operations.
+```
+
+If issues remain after 10 passes, list as unresolved with suggestions.

package/skills/choose-wisely/lib/bootstrap.md

@@ -0,0 +1,92 @@
+# Bootstrap Module — Extract Choices from Docs
+
+Scan existing documentation and extract implicit architectural decisions.
+
+## Sources to Scan
+
+Priority order:
+1. `README.md` — project overview, mission
+2. `ARCHITECTURE.md` — system design
+3. `DESIGN.md` — design decisions
+4. `CLAUDE.md` — AI agent instructions
+5. `.pi/agent/AGENTS.md` — project guidelines
+6. `docs/*.md` — additional docs
+7. `specs/*.md` — specifications
+8. ADR files (`docs/adr/*.md`, `adr/*.md`)
+
+## Extraction Mapping
+
+| Found In | Section |
+|----------|---------|
+| Mission statements, values, principles | **Mission** (M-) |
+| User journeys, interaction patterns | **User Experiences** (UX-) |
+| Specific capabilities, behaviors | **Features** (F-) |
+| Automation, SLAs, moderation | **Operations** (O-) |
+| Schema decisions, storage patterns | **Data** (D-) |
+| System design, module structure | **Architecture** (A-) |
+| Named technologies, libraries | **Technology** (T-) |
+| Dev practices, coding standards | **Implementation** (I-) |
+
+## Extraction Process
+
+For each document:
+
+1. **Identify decisions** — statements of intent, choices made, patterns adopted
+2. **Classify by section** — which of 8 sections does this belong to?
+3. **Extract rationale** — why was this chosen? (1-2 sentences)
+4. **Note alternatives** — what else was considered?
+5. **Find dependencies** — what does this support / depend on?
+
+## Output Format
+
+```yaml
+choices:
+  - section: Mission
+    title: Core value proposition
+    rationale: Build X because Y
+    source: README.md:12
+    supports: []
+  - section: Technology
+    title: Use PostgreSQL for primary database
+    rationale: ACID compliance needed for financial data
+    source: ARCHITECTURE.md:45
+    supports: [D-0001]
+```
+
+## Deduplication
+
+- Same concept, different wording → merge, keep clearest rationale
+- Similar but distinct → keep separate
+- Contradictory → flag as conflict
+
+## Conflict Marking
+
+```markdown
+### A-0012: Data storage approach
+Supports: F-0003
+
+<!-- CONFLICT: README.md says PostgreSQL, ARCHITECTURE.md says MongoDB -->
+Use PostgreSQL for transactional data, MongoDB for documents.
+```
+
+## Gap Detection
+
+After extraction, flag:
+
+1. **Undefined terms** — used in 3+ choices but not explained
+2. **Missing scope** — Mission doesn't answer: who, what, platform
+3. **Phantom references** — "9 data stores" but only 3 listed
+4. **Opaque names** — component/module names without explanation
+
+## ID Assignment
+
+Within each section:
+- Order by priority (most constraining first)
+- Assign sequential IDs: M-0001, M-0002, UX-0001, F-0001, etc.
+
+## Final Steps
+
+1. Write all choices to CHOICES.md
+2. Present summary (N choices, M sources, P conflicts, G gaps)
+3. Walk through conflicts with user
+4. Run audit to validate

package/skills/choose-wisely/lib/cascade.md

@@ -0,0 +1,138 @@
+# Cascade Module — Impact Review
+
+Three-check cascade for propagating change impacts through the choice hierarchy.
+
+## Principle
+
+Changing a choice can affect:
+1. What it supports (upward)
+2. Peers in same section (lateral)
+3. What depends on it (downward)
+
+## The Three Checks
+
+### Check 1: Upward — Support Integrity
+
+**Question:** Does the changed choice still support its `Supports:` targets?
+
+```
+Before: A-0012 "Use event queue" supports F-0003 "Real-time updates"
+Change: A-0012 → "Use synchronous API calls"
+Check: Does sync API still support real-time updates? NO
+Result: Flag broken support, suggest alternatives
+```
+
+Actions:
+- Verify support still holds
+- If weakened: note degraded support
+- If broken: flag and propose alternatives
+
+### Check 2: Lateral — Section Coherence
+
+**Question:** Any contradictions or redundancies with peer choices?
+
+```
+Section: Technology
+Existing: T-0003 "Use PostgreSQL for transactions"
+Change: Add T-0008 "Use MongoDB for all data"
+Check: Contradiction! Can't use both for all data
+Result: Flag conflict, ask user to resolve
+```
+
+Actions:
+- Scan same section for contradictions
+- Identify redundancies (same decision twice)
+- Check ordering (more constraining first)
+
+### Check 3: Downward — Impact Propagation
+
+**Question:** Do choices that reference this one still hold?
+
+```
+Changed: A-0012 "Use event queue" → "Use synchronous API"
+Dependents:
+  - D-0005 "Store events in Kafka" (supports A-0012)
+  - O-0003 "Async event processing" (supports A-0012)
+
+Check: These depend on event queue. Sync API invalidates them.
+Result: Propose modifications to D-0005, O-0003
+```
+
+Actions:
+- Find all choices with changed ID in their `Supports:`
+- Assess if dependency still valid
+- Propose modifications → re-enters cascade
+
+## Cascade Algorithm
+
+```
+function cascade(change, depth=0):
+  if depth > 10:
+    return "Max depth exceeded"
+
+  issues = []
+
+  # Check 1: Upward
+  for target in change.supports:
+    if not supports_target(change, target):
+      issues.append(broken_support(change, target))
+
+  # Check 2: Lateral
+  for peer in get_section_peers(change.section):
+    if contradicts(change, peer):
+      issues.append(contradiction(change, peer))
+    if redundant(change, peer):
+      issues.append(redundancy(change, peer))
+
+  # Check 3: Downward
+  for dependent in get_dependents(change.id):
+    if not dependency_holds(dependent, change):
+      proposed = propose_fix(dependent, change)
+      issues.append(impact(dependent, proposed))
+      cascade(proposed, depth + 1)  # Recurse
+
+  return issues
+```
+
+## Convergence
+
+Cascade recursively until:
+- No new issues found
+- Max depth (10) reached
+
+## Output
+
+Run silently. When converged, summarize tersely:
+
+> Updated "event architecture" choice. Cascade found 2 impacts: "Kafka storage" choice now needs revision, "async processing" choice marked for review. Fixed stale reference. 4 choices touched total.
+
+## Example Session
+
+```
+User: Change A-0012 from event queue to synchronous API
+
+Analyzing change...
+Check 1: A-0012 supports F-0003 "real-time updates"
+  → Sync API weakens support. Flag for review.
+
+Check 2: Lateral scan of Architecture section
+  → No contradictions found.
+
+Check 3: Finding dependents...
+  → D-0005 "Kafka storage" depends on A-0012
+  → O-0003 "Async processing" depends on A-0012
+  → Both invalidated by sync API change.
+
+Cascade continues...
+  → Proposing D-0005 revision: "HTTP request storage"
+  → Proposing O-0003 revision: "Synchronous processing"
+
+Converged after 2 passes.
+
+Summary: Changed "event architecture" to synchronous. 3 downstream choices affected:
+- D-0005: Kafka → HTTP logs
+- O-0003: Async → Sync processing
+- F-0003: Real-time capability degraded (warning)
+
+Proceed with these changes?
+```

package/skills/choose-wisely/lib/interview.md

@@ -0,0 +1,190 @@
+# Interview Module — Planning Questions
+
+Structured interview for discovering architectural decisions.
+
+## When to Use
+
+- New project with no CHOICES.md
+- Major replanning needed
+- User explicitly requests planning
+
+## Interview Categories
+
+Ask questions in this order, grouped by section.
+
+### Mission (M-*)
+
+Core questions:
+1. **Problem** — What problem does this solve?
+2. **Users** — Who are the primary users?
+3. **Value** — What's the core value proposition?
+4. **Scope** — What's explicitly in/out of scope?
+
+Example prompts:
+- "What pain point are you addressing?"
+- "Who wakes up excited to use this?"
+- "In one sentence, why does this exist?"
+
+### User Experiences (UX-*)
+
+Core questions:
+1. **Workflow** — What's the primary user journey?
+2. **Interactions** — How do users interact with this?
+3. **Easy vs Powerful** — What should be effortless? What should be configurable?
+4. **Errors** — How should failures appear to users?
+
+Example prompts:
+- "Walk me through a typical user session"
+- "What's the happy path? What's the sad path?"
+
+### Features (F-*)
+
+Core questions:
+1. **Core capabilities** — What must it do?
+2. **Nice-to-have** — What would be nice but not required?
+3. **Differentiators** — What makes this different from alternatives?
+4. **Integrations** — What must it connect to?
+
+Example prompts:
+- "If you could only have 3 features, which ones?"
+- "What would make users switch from competitors?"
+
+### Operations (O-*)
+
+Core questions:
+1. **Deployment** — Where does this run?
+2. **Scaling** — How does it handle growth?
+3. **Monitoring** — How do you know it's healthy?
+4. **Recovery** — What happens when things break?
+
+Example prompts:
+- "How many concurrent users at peak?"
+- "What's acceptable downtime?"
+
+### Data (D-*)
+
+Core questions:
+1. **Storage** — What data must persist?
+2. **Access patterns** — How is data read/written?
+3. **Privacy** — What's sensitive? Who can see what?
+4. **Retention** — How long is data kept?
+
+Example prompts:
+- "What would be catastrophic to lose?"
+- "Does data have different access speeds?"
+
+### Architecture (A-*)
+
+Core questions:
+1. **Structure** — Monolith or distributed?
+2. **Communication** — Sync or async?
+3. **Boundaries** — How do components interact?
+4. **Resilience** — Single points of failure?
+
+Example prompts:
+- "Do components need to scale independently?"
+- "What happens if one piece goes down?"
+
+### Technology (T-*)
+
+Core questions:
+1. **Stack** — What languages/frameworks?
+2. **Databases** — What storage systems?
+3. **Infrastructure** — Where is it hosted?
+4. **Constraints** — Any technology mandates or prohibitions?
+
+Example prompts:
+- "What does your team already know well?"
+- "Any tech debt or legacy constraints?"
+
+### Implementation (I-*)
+
+Core questions:
+1. **Process** — How is code written and reviewed?
+2. **Testing** — What testing strategy?
+3. **CI/CD** — How is code deployed?
+4. **Standards** — Any coding conventions?
+
+Example prompts:
+- "How do you ensure code quality?"
+- "What's your release cadence?"
+
+## Question Format
+
+For each decision point:
+
+```
+Q: {question}?
+
+Options:
+A) {option} — {tradeoff}
+B) {option} — {tradeoff}
+C) {option} — {tradeoff}
+
+[Your choice]: _
+```
+
+## Recording Decisions
+
+For each answer:
+
+```markdown
+### X-0001: {title}
+Supports: {parent IDs}
+
+{rationale derived from answer}
+
+Alternatives considered: {options not chosen}
+```
+
+## Interview Flow
+
+1. **Discovery** — Scan existing code/docs for context
+2. **Questions** — Ask by section, 1-3 per section
+3. **Clarification** — Ask follow-ups if answers are vague
+4. **Synthesis** — Convert answers to CHOICES.md format
+5. **Review** — Show summary, ask for corrections
+6. **Generate** — Write CHOICES.md + PLAN.md
+
+## Example
+
+```
+## Mission Questions
+
+Q1: What problem does this solve?
+    A) Developers need faster API development
+    B) Teams need better collaboration tools
+    C) Users need simpler data visualization
+
+User: A
+
+Q2: Who are the primary users?
+    A) Backend developers
+    B) Full-stack teams
+    C) API product managers
+
+User: B
+
+Recording:
+  M-0001: Accelerate API development for full-stack teams
+  Supports: (none - top level)
+
+  Full-stack teams spend too much time on boilerplate.
+  This tool reduces API setup from hours to minutes.
+
+[Continues through sections...]
+
+## Summary
+
+Generated 18 choices across 8 sections:
+- Mission: 2
+- User Experiences: 3
+- Features: 5
+- Operations: 2
+- Data: 2
+- Architecture: 2
+- Technology: 1
+- Implementation: 1
+
+Review CHOICES.md? [y/n]
+```

package/skills/replan/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: replan
+description: "Gap analysis: compare CHOICES.md against current state, generate PLAN.md for next implementation phase."
+allowed-tools: Read, Glob, Grep, Bash, Edit
+---
+
+# Replan — Gap Analysis & Plan Generation
+
+Compare CHOICES.md goals against current implementation. Generate PLAN.md for next phase.
+
+## When to Use
+
+- Current PLAN.md is 100% complete
+- Major scope change requires new planning
+- User asks to "replan" or "next phase"
+- Starting fresh implementation cycle
+
+## Workflow
+
+### 1. Read CHOICES.md
+
+Parse all 8 sections, extract:
+- Choice ID, title, decision
+- `Supports:` dependencies
+- Section ordering (M > UX > F > O > D > A > T > I)
+
+### 2. Analyze Current State
+
+Check implementation status:
+
+```bash
+# What's been committed?
+git log --oneline -20
+
+# What's the current structure?
+find . -type f -name "*.ts" -o -name "*.py" -o -name "*.js" | head -50
+
+# Any existing PLAN.md?
+cat PLAN.md 2>/dev/null || echo "No PLAN.md"
+
+# Memory/log of what's done?
+cat MEMORY.md 2>/dev/null || cat .pi/memory.md 2>/dev/null || echo "No memory file"
+```
+
+### 3. Categorize Choices
+
+| Status | Criteria |
+|--------|----------|
+| **Fulfilled** | Code exists, tests pass, documented |
+| **Partial** | Started but incomplete |
+| **Not started** | No implementation evidence |
+
+### 4. Prioritize Unfulfilled
+
+Order by:
+1. Section priority (M > UX > F > O > D > A > T > I)
+2. Dependencies (unblocked first)
+3. Impact (high-impact choices first)
+
+### 5. Generate PLAN.md
+
+Use [plan template](../templates/PLAN.md). Group into phases:
+
+```markdown
+## Phase 1: {Focused Goal}
+### Steps
+- [ ] 1.1 {Action verb} {specific thing}
+- [ ] 1.2 {Action verb} {specific thing}
+
+### Gates
+- [ ] {Testable criterion}
+```
+
+**Rules:**
+- 3-7 steps per phase
+- 1-3 gates per phase
+- Gates must be testable (can run command, check output)
+- Max 300 lines total
+
+### 6. Validate Plan
+
+Run plan validation checks:
+- [ ] Line count ≤ 300
+- [ ] Objective section present
+- [ ] Each phase has Steps + Gates
+- [ ] Steps are actionable (start with verb)
+- [ ] Gates are testable (not subjective)
+- [ ] Scope defined (In/Out)
+
+### 7. Output
+
+```
+Gap Analysis Complete
+
+CHOICES.md: {N} choices
+  ✓ Fulfilled: {a}
+  ◐ Partial: {b}
+  ✗ Not started: {c}
+
+PLAN.md generated: {M} phases, {K} tasks
+  Phase 1: {name} ({n} steps)
+  Phase 2: {name} ({n} steps)
+  ...
+
+Ready to implement. Run /choose-wisely:replan again when complete.
+```
+
+## Example
+
+```
+User: /choose-wisely:replan
+
+Analyzing CHOICES.md...
+  M-0001: Real-time chat platform — fulfilled ✓
+  UX-0001: Channel-based messaging — fulfilled ✓
+  F-0003: Video integration — partial ◐
+  F-0008: Search — not started ✗
+  O-0012: Monitoring — not started ✗
+
+Gap Analysis Complete
+
+CHOICES.md: 23 choices
+  ✓ Fulfilled: 8
+  ◐ Partial: 2
+  ✗ Not started: 13
+
+PLAN.md generated: 3 phases, 24 tasks
+  Phase 1: Search implementation (8 steps)
+  Phase 2: Video completion (6 steps)
+  Phase 3: Monitoring setup (5 steps)
+
+Ready to implement.
+```
+
+## Integration
+
+After PLAN.md is 100% complete:
+1. Run `/choose-wisely:replan` again for next phase
+2. Or update CHOICES.md with new decisions first
+3. Cycle continues until all choices fulfilled

package/templates/CHOICES.md

@@ -0,0 +1,66 @@
+# CHOICES.md — Source of Plan
+
+All project choices in priority order. Higher choices constrain lower ones.
+Use `/choose-wisely:choose` to add, change, remove, or reorder choices.
+Use `/choose-wisely:choose-audit` to check for contradictions and structural issues.
+
+## Rules
+
+- **Position = Priority**: higher constrains lower, no exceptions
+- **Gravity rule**: changing a choice triggers cascading review
+- **Section order is fixed**: Mission > User Experiences > Features > Operations > Data > Architecture > Technology > Implementation
+- **Supports line required**: every choice (except top) lists IDs it directly supports
+- **Architecture is tool-agnostic**: Architecture describes patterns; Technology names tools
+- **No status values**: git diff is the change record
+
+### Choice Entry Format
+
+```
+### X-0001: Title of choice
+Supports: X-0000, Y-0000
+
+One to two lines of rationale. Not a spec. Just why this choice was made.
+```
+
+- ID format: `PREFIX-NNNN` (globally unique 4-digit number)
+- Prefixes: `M-` (Mission), `UX-` (User Experiences), `F-` (Features), `O-` (Operations), `D-` (Data), `A-` (Architecture), `T-` (Technology), `I-` (Implementation)
+
+---
+
+## Mission
+<!-- Why we exist, values, principles. Everything else flows from here. -->
+
+---
+
+## User Experiences
+<!-- Core user journeys, interaction patterns. -->
+
+---
+
+## Features
+<!-- Specific capabilities and behaviors. -->
+
+---
+
+## Operations
+<!-- Automation vs human-in-loop, workflows, SLAs, moderation. -->
+
+---
+
+## Data
+<!-- Data model, schemas, storage decisions. -->
+
+---
+
+## Architecture
+<!-- System design, module structure, communication patterns. Tool-agnostic. -->
+
+---
+
+## Technology
+<!-- Tech stack, libraries, infrastructure. Names specific tools. -->
+
+---
+
+## Implementation
+<!-- Dev practices, coding standards, deployment patterns. -->

package/templates/PLAN.md

@@ -0,0 +1,42 @@
+# Plan
+
+## Objective
+
+{What you're building, why, and expected outcome in 2-5 sentences.}
+
+## Scope
+
+**In Scope:**
+- {Specific deliverable 1}
+- {Specific deliverable 2}
+
+**Out of Scope:**
+- {Explicitly excluded item}
+
+---
+
+## Phase 1: {Phase Name}
+
+### Steps
+- [ ] 1.1 {Concrete action starting with verb}
+- [ ] 1.2 {Concrete action starting with verb}
+- [ ] 1.3 {Concrete action starting with verb}
+
+### Gates
+- [ ] {Testable criterion with command or check}
+- [ ] {Testable criterion with command or check}
+
+---
+
+## Current Phase: 1
+## Status: not-started
+
+---
+
+## Success Criteria
+
+Overall verification that the objective is achieved:
+
+- [ ] {Final testable criterion 1}
+- [ ] {Final testable criterion 2}
+- [ ] {Final testable criterion 3}