mindsystem-cc 3.2.2 → 3.3.0

package/commands/ms/execute-phase.md

@@ -61,38 +61,45 @@ Phase: $ARGUMENTS
    - Collect summaries from all plans
    - Report phase completion status
 
-6. **Verify phase goal**
+6. **Simplify code (optional)**
+   - Read `simplifier` from config.json (default: `ms-code-simplifier`)
+   - If `"skip"`: proceed to step 7
+   - Spawn simplifier agent with phase file scope
+   - If changes made: commit as `refactor({phase}): simplify phase code`
+
+7. **Verify phase goal**
    - Spawn `ms-verifier` subagent with phase directory and goal
    - Verifier checks must_haves against actual codebase (not SUMMARY claims)
    - Creates VERIFICATION.md with detailed report
    - Route by status:
-     - `passed` → continue to step 7
+     - `passed` → continue to step 8
      - `human_needed` → present items, get approval or feedback
      - `gaps_found` → present gaps, offer `/ms:plan-phase {X} --gaps`
 
-7. **Generate phase patch**
+8. **Generate phase patch**
    - Run: `~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER}`
    - Outputs to `.planning/phases/{phase_dir}/{phase}-changes.patch`
    - Verify: patch file exists OR skip message logged
+   - Note: Patch captures all changes including simplifications
 
-8. **Update roadmap and state**
+9. **Update roadmap and state**
    - Update ROADMAP.md, STATE.md
 
-9. **Update requirements**
-   Mark phase requirements as Complete:
-   - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
-   - Read REQUIREMENTS.md traceability table
-   - For each REQ-ID in this phase: change Status from "Pending" to "Complete"
-   - Write updated REQUIREMENTS.md
-   - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
+10. **Update requirements**
+    Mark phase requirements as Complete:
+    - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
+    - Read REQUIREMENTS.md traceability table
+    - For each REQ-ID in this phase: change Status from "Pending" to "Complete"
+    - Write updated REQUIREMENTS.md
+    - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
 
-10. **Commit phase completion**
+11. **Commit phase completion**
     Bundle all phase metadata updates in one commit:
     - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
     - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
     - Commit: `docs({phase}): complete {phase-name} phase`
 
-11. **Offer next steps**
+12. **Offer next steps**
     - Route to next action (see `<offer_next>`)
 </process>
 
@@ -261,9 +268,16 @@ After all tasks in a plan complete:
 2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
 3. NO code files (already committed per-task)
 
+**Simplification Commit (if changes made):**
+
+After code simplification step:
+1. Stage only simplified files
+2. Commit with format: `refactor({phase}): simplify phase code`
+3. Include simplifier agent name and file count in commit body
+
 **Phase Completion Commit:**
 
-After all plans in phase complete (step 7):
+After all plans in phase complete:
 1. Stage: ROADMAP.md, STATE.md, REQUIREMENTS.md (if updated), VERIFICATION.md
 2. Commit with format: `docs({phase}): complete {phase-name} phase`
 3. Bundles all phase-level state updates in one commit
@@ -279,6 +293,7 @@ After all plans in phase complete (step 7):
 <success_criteria>
 - [ ] All incomplete plans in phase executed
 - [ ] Each plan has SUMMARY.md
+- [ ] Code simplified (or skipped if config says "skip")
 - [ ] Phase goal verified (must_haves checked against codebase)
 - [ ] VERIFICATION.md created in phase directory
 - [ ] Patch file generated OR explicitly skipped with message

package/commands/ms/help.md

@@ -82,10 +82,9 @@ Common deviations:
 **`/ms:new-project`**
 Initialize new project with brief and configuration.
 
-- Use when: you want Mindsystem to set up `.planning/` and capture intent (new repo, or an existing repo where you’re adding/changing work).
+- Use when: you want Mindsystem to set up `.planning/` and capture intent (new repo, or an existing repo where you're adding/changing work).
 - Creates `.planning/PROJECT.md` (vision and requirements)
-- Creates `.planning/config.json` (workflow mode)
-- Asks for workflow mode (interactive/yolo) upfront
+- Creates `.planning/config.json` (workflow settings)
 - Commits initialization files to git
 
 Usage: `/ms:new-project`
@@ -159,7 +158,7 @@ Audit and improve design of already-implemented features.
 - Creates retroactive DESIGN.md if none exists
 - Presents improvements with benefits and trade-offs
 - Applies user-approved changes, runs verification
-- Use for features implemented before GSD, or periodic design audits
+- Use for features implemented before Mindsystem, or periodic design audits
 
 Usage: `/ms:review-design 4` (review phase 4)
 Usage: `/ms:review-design lib/features/home/home_screen.dart`
@@ -427,7 +426,7 @@ Usage: `/ms:update`
 ├── REQUIREMENTS.md       # Scoped v1/v2 requirements
 ├── ROADMAP.md            # Current phase breakdown
 ├── STATE.md              # Project memory & context
-├── config.json           # Workflow mode & gates
+├── config.json           # Workflow settings
 ├── research/             # Domain ecosystem research
 ├── todos/                # Captured ideas and tasks
 │   ├── pending/          # Todos waiting to be worked on
@@ -457,24 +456,6 @@ Usage: `/ms:update`
         └── 02-01-SUMMARY.md
 ```
 
-## Workflow Modes
-
-Set during `/ms:new-project`:
-
-**Interactive Mode**
-
-- Confirms each major decision
-- Pauses at checkpoints for approval
-- More guidance throughout
-
-**YOLO Mode**
-
-- Auto-approves most decisions
-- Executes plans without confirmation
-- Only stops for critical checkpoints
-
-Change anytime by editing `.planning/config.json`
-
 ## Common Workflows
 
 **Starting a new project (greenfield):**

package/commands/ms/new-milestone.md

@@ -30,9 +30,6 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 @.planning/STATE.md
 @.planning/MILESTONES.md
 @.planning/config.json
-
-**Load milestone context (if exists, from /ms:discuss-milestone):**
-@.planning/MILESTONE-CONTEXT.md
 </context>
 
 <process>
@@ -41,14 +38,15 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    - Read PROJECT.md (existing project, Validated requirements, decisions)
    - Read MILESTONES.md (what shipped previously)
    - Read STATE.md (pending todos, blockers)
-   - Check for MILESTONE-CONTEXT.md (from /ms:discuss-milestone)
+   - Calculate previous milestone version from MILESTONES.md (e.g., if last shipped was v1.0, previous=1.0)
+   - Note: Previous milestone files will be loaded on-demand based on user's choice in step 3
+
+   **Why only the last milestone?** We load DECISIONS.md and AUDIT.md from only the immediately preceding milestone. Older decisions that remain important should already be in PROJECT.md or visible in the codebase. Older untested assumptions that weren't addressed in subsequent milestones are intentionally skipped or no longer relevant. Loading all previous milestones would bloat context for diminishing returns.
 
 2. **Present what shipped (if MILESTONES.md exists):**
 
    ```bash
    cat .planning/MILESTONES.md 2>/dev/null
-   # Also check for assumptions from last audit
-   cat .planning/v*-MILESTONE-AUDIT.md 2>/dev/null | grep -A 100 "assumptions:" | head -50
    ```
 
    Format the presentation:
@@ -63,7 +61,6 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    **Key accomplishments:**
    - [From MILESTONES.md accomplishments]
    - [From MILESTONES.md accomplishments]
-   - [From MILESTONES.md accomplishments]
 
    **Validated requirements:**
    - [From PROJECT.md Validated section]
@@ -71,37 +68,56 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    **Pending todos (if any):**
    - [From STATE.md accumulated context]
 
-   **Untested assumptions (if any):**
-   - [From MILESTONE-AUDIT.md assumptions section]
-   - Error state displays (04-comments, 05-auth)
-   - Empty state handling (04-comments)
-   - Session timeout behavior (05-auth)
-
-   *These were skipped during UAT because required states couldn't be mocked.*
-
    ---
    ```
 
-   This gives users context before asking what they want to build next.
+3. **Decision gate:**
 
-3. **Gather milestone goals:**
+   Use AskUserQuestion:
+   - header: "New Milestone"
+   - question: "How do you want to start?"
+   - options:
+     - "I know what to build" — proceed to goal gathering
+     - "Help me figure it out" — enter discovery mode with previous context
+     - "Show previous decisions first" — view DECISIONS.md and AUDIT.md, then decide
 
-   **If MILESTONE-CONTEXT.md exists:**
-   - Use features and scope from discuss-milestone
-   - Present summary for confirmation
+4. **Gather milestone goals:**
 
-   **If no context file:**
-   - Present what shipped in last milestone
-   - Ask: "What do you want to build next?"
+   **If "I know what to build":**
+   - Ask directly: "What do you want to build next?"
    - Use AskUserQuestion to explore features
    - Probe for priorities, constraints, scope
 
-4. **Determine milestone version:**
+   **If "Show previous decisions first":**
+   - Using the previous version calculated in step 1 (e.g., "1.0"):
+     - Check for and read `.planning/milestones/v1.0-DECISIONS.md` if exists
+     - Check for and read `.planning/milestones/v1.0-MILESTONE-AUDIT.md` if exists
+   - Present relevant context from these files
+   - Return to decision gate (without this option)
+
+   **If "Help me figure it out" (Discovery Mode):**
+   - Using the previous version calculated in step 1:
+     - Check for and read `.planning/milestones/v{VERSION}-DECISIONS.md` if exists
+     - Check for and read `.planning/milestones/v{VERSION}-MILESTONE-AUDIT.md` if exists
+   - Surface untested assumptions from AUDIT.md (if found):
+     ```
+     📋 Untested from v[previous]:
+     - Error state displays
+     - Empty state handling
+     - [etc. from assumptions section]
+     ```
+   - Follow questioning.md patterns for AskUserQuestion-based discovery:
+     - "What do you want to add, improve, or fix?"
+     - Options: Address untested assumptions, New features, Improvements, Bug fixes, Let me describe
+   - Follow up with probing questions
+   - Continue until clear goals emerge
+
+5. **Determine milestone version:**
    - Parse last version from MILESTONES.md
    - Suggest next version (v1.0 → v1.1, or v2.0 for major)
    - Confirm with user
 
-5. **Update PROJECT.md:**
+6. **Update PROJECT.md:**
 
    Add/update these sections:
 
@@ -120,7 +136,7 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
    Update "Last updated" footer.
 
-6. **Update STATE.md:**
+7. **Update STATE.md:**
 
    ```markdown
    ## Current Position
@@ -131,9 +147,6 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    Last activity: [today] — Milestone v[X.Y] started
    ```
 
-7. **Cleanup:**
-   - Delete MILESTONE-CONTEXT.md if exists (consumed)
-
 8. **Git commit:**
    ```bash
    git add .planning/PROJECT.md .planning/STATE.md
@@ -187,7 +200,6 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 - PROJECT.md updated with Current Milestone section
 - Active requirements reflect new milestone goals
 - STATE.md reset for new milestone
-- MILESTONE-CONTEXT.md consumed and deleted (if existed)
 - Git commit made
 - User routed to define-requirements (or research-project)
 </success_criteria>

package/commands/ms/new-project.md

@@ -217,28 +217,19 @@ Do not compress. Capture everything gathered.
 
 <step name="workflow_preferences">
 
-Ask all workflow preferences in a single AskUserQuestion call (3 questions):
+Ask workflow preferences in a single AskUserQuestion call (2 questions):
 
 Use AskUserQuestion with questions array:
 
 ```
 questions: [
-  {
-    header: "Mode",
-    question: "How do you want to work?",
-    multiSelect: false,
-    options: [
-      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
-      { label: "Interactive", description: "Confirm at each step" }
-    ]
-  },
   {
     header: "Depth",
     question: "How thorough should planning be?",
     multiSelect: false,
     options: [
       { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
+      { label: "Standard (Recommended)", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
       { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
     ]
   },
@@ -263,7 +254,7 @@ questions: [
 
 <step name="config">
 
-Create `.planning/config.json` with chosen mode, depth, and parallelization using `templates/config.json` structure.
+Create `.planning/config.json` with chosen depth and parallelization using `templates/config.json` structure.
 
 </step>
 
@@ -291,7 +282,7 @@ Present completion with next steps (see ~/.claude/mindsystem/references/continua
 Project initialized:
 
 - Project: .planning/PROJECT.md
-- Config: .planning/config.json (mode: [chosen mode])
+- Config: .planning/config.json
 [If .planning/codebase/ exists:] - Codebase: .planning/codebase/ (7 documents)
 
 ---
@@ -332,7 +323,7 @@ Skip research, define requirements from what you know, then create roadmap.
 - [ ] PROJECT.md captures full context with evolutionary structure
 - [ ] Requirements initialized as hypotheses (greenfield) or with inferred Validated (brownfield)
 - [ ] Key Decisions table initialized
-- [ ] config.json has workflow mode, depth, and parallelization
+- [ ] config.json has depth and parallelization settings
 - [ ] All committed to git
 
 </success_criteria>

package/commands/ms/progress.md

@@ -380,5 +380,5 @@ Ready to plan the next milestone.
 - [ ] What's next clearly explained
 - [ ] Smart routing: /ms:execute-phase if plan exists, /ms:plan-phase if not
 - [ ] User confirms before any action
-- [ ] Seamless handoff to appropriate gsd command
+- [ ] Seamless handoff to appropriate mindsystem command
       </success_criteria>

package/commands/ms/research-project.md

@@ -299,8 +299,16 @@ Create SUMMARY.md with:
 - Confidence assessment
 - Gaps to address
 
+After creating SUMMARY.md, update config.json simplifier with agent name:
+1. Read recommended stack from STACK.md
+2. Map to simplifier agent name:
+   - Flutter/Dart → \"ms-flutter-simplifier\"
+   - All others → \"ms-code-simplifier\"
+3. Update .planning/config.json (create from template if needed)
+
 Then commit ALL research files together:
 git add .planning/research/
+git add .planning/config.json
 git commit -m 'docs: complete [domain] project research'
 ",
   subagent_type="ms-research-synthesizer",

package/commands/ms/review-design.md

@@ -60,7 +60,7 @@ Options:
 - "Uncommitted changes" - Review files with uncommitted modifications
 - "Specific file" - I'll provide a file path
 - "Recent feature work" - Review files from recent commits
-- "GSD phase" - Review all code from a specific phase
+- "Mindsystem phase" - Review all code from a specific phase
 ```
 
 ### Step 1.2: Resolve Phase Directory (if phase-based)

package/commands/ms/whats-new.md

@@ -38,7 +38,7 @@ STOP here if no VERSION file.
 Fetch latest CHANGELOG.md from GitHub:
 
 Use WebFetch tool with:
-- URL: `https://raw.githubusercontent.com/rolandtolnay/gsd/main/CHANGELOG.md`
+- URL: `https://raw.githubusercontent.com/rolandtolnay/mindsystem/main/CHANGELOG.md`
 - Prompt: "Extract all version entries with their dates and changes. Return in Keep-a-Changelog format."
 
 **If fetch fails:**
@@ -75,7 +75,7 @@ Format output clearly:
 
 You're on the latest version.
 
-[View full changelog](https://github.com/rolandtolnay/gsd/blob/main/CHANGELOG.md)
+[View full changelog](https://github.com/rolandtolnay/mindsystem/blob/main/CHANGELOG.md)
 ```
 
 **If updates available:**
@@ -105,7 +105,7 @@ You're on the latest version.
 
 ---
 
-[View full changelog](https://github.com/rolandtolnay/gsd/blob/main/CHANGELOG.md)
+[View full changelog](https://github.com/rolandtolnay/mindsystem/blob/main/CHANGELOG.md)
 
 **To update:** `npx mindsystem-cc --global`
 ```

package/mindsystem/references/git-integration.md

@@ -1,5 +1,5 @@
 <overview>
-Git integration for GSD framework.
+Git integration for Mindsystem framework.
 </overview>
 
 <core_principle>
@@ -29,7 +29,7 @@ The git log should read like a changelog of what shipped, not a diary of plannin
 [ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
 ```
 
-If NO_GIT: Run `git init` silently. GSD projects always get their own repo.
+If NO_GIT: Run `git init` silently. Mindsystem projects always get their own repo.
 </git_check>
 
 <commit_formats>

package/mindsystem/references/goal-backward.md

@@ -255,7 +255,7 @@ Key links are verification priorities. Without them, you check everything equall
 
 </common_failures>
 
-<integration_with_gsd>
+<integration_with_mindsystem>
 
 ## In plan-phase.md
 
@@ -283,4 +283,4 @@ derive_must_haves → tasks → execute → verify → [gaps?] → fix plans →
 
 Must-haves are derived once, verified as many times as needed until all pass.
 
-</integration_with_gsd>
+</integration_with_mindsystem>

package/mindsystem/references/principles.md

@@ -1,6 +1,6 @@
 <principles>
 
-Core principles for the GSD planning system.
+Core principles for the Mindsystem planning system.
 
 <solo_developer_claude>
 

package/mindsystem/templates/adhoc-summary.md

@@ -17,6 +17,7 @@ files_modified:
   - [path/to/file1.ts]
   - [path/to/file2.ts]
 commit: [git hash]
+patch_file: [path to .patch file, or empty if skipped]
 ---
 
 # Adhoc: [Description]
@@ -66,6 +67,7 @@ Adhoc summaries document small work items executed outside the normal phase work
 | related_phase | Yes | Current phase from STATE.md, or "none" if between phases |
 | files_modified | Yes | List of file paths changed |
 | commit | Yes | Git commit hash |
+| patch_file | No | Path to generated patch file (empty if no code changes) |
 
 </frontmatter_fields>
 
@@ -100,6 +102,7 @@ files_modified:
   - src/lib/api-client.ts
   - src/hooks/useAuth.ts
 commit: abc123f
+patch_file: .planning/adhoc/2026-01-20-fix-auth-token-not-refreshing-on-401.patch
 ---
 
 # Adhoc: Fix auth token not refreshing on 401

package/mindsystem/templates/codebase/architecture.md

@@ -146,7 +146,7 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 
 **CLI Command Execution:**
 
-1. User runs: `gsd new-project`
+1. User runs: `ms new-project`
 2. Commander parses args and flags
 3. Command handler invoked (`src/commands/new-project.ts`)
 4. Handler calls service methods (`src/services/project.ts` → `create()`)
@@ -180,7 +180,7 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 
 **CLI Entry:**
 - Location: `src/index.ts`
-- Triggers: User runs `gsd <command>`
+- Triggers: User runs `ms <command>`
 - Responsibilities: Register commands, parse args, display help
 
 **Commands:**

package/mindsystem/templates/codebase/structure.md

@@ -145,7 +145,7 @@ mindsystem/
 - Key files: install.js - handles npx installation
 - Subdirectories: None
 
-**commands/gsd/**
+**commands/ms/**
 - Purpose: Slash command definitions for Claude Code
 - Contains: *.md files (one per command)
 - Key files: new-project.md, plan-phase.md, execute-plan.md

package/mindsystem/templates/config.json

@@ -1,5 +1,4 @@
 {
-  "mode": "interactive",
   "depth": "standard",
   "parallelization": {
     "enabled": true,
@@ -9,18 +8,9 @@
     "max_concurrent_agents": 3,
     "min_plans_for_parallel": 2
   },
-  "gates": {
-    "confirm_project": true,
-    "confirm_phases": true,
-    "confirm_roadmap": true,
-    "confirm_breakdown": true,
-    "confirm_plan": true,
-    "execute_next_plan": true,
-    "issues_review": true,
-    "confirm_transition": true
-  },
   "safety": {
     "always_confirm_destructive": true,
     "always_confirm_external_services": true
-  }
+  },
+  "simplifier": null
 }

package/mindsystem/templates/decisions.md

@@ -0,0 +1,145 @@
+# Decisions Template
+
+Template for `.planning/milestones/v{X.Y}-DECISIONS.md` — consolidated decisions from a milestone.
+
+**Purpose:** Preserve decision rationale for future reference. When starting a new milestone, previous DECISIONS.md provides context for "why did we do it this way?"
+
+**Created by:** `ms-consolidator` agent during `/ms:complete-milestone`
+
+**Referenced by:** `/ms:new-milestone` during discovery mode
+
+---
+
+<template>
+
+```markdown
+# Milestone v{{VERSION}} Decisions
+
+**Milestone:** {{NAME}}
+**Phases:** {{PHASE_START}}-{{PHASE_END}}
+**Consolidated:** {{DATE}}
+
+---
+
+## Technical Stack
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## Architecture
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## Data Model
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## API Design
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## UI/UX
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## Security
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## Performance
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+---
+
+## Sources
+
+Files consolidated from each phase:
+
+| Phase | Files Found |
+|-------|-------------|
+| {{PHASE_NUM}} | {{FILES_LIST}} |
+
+---
+
+*Consolidated: {{DATE}} during v{{VERSION}} milestone completion*
+```
+
+</template>
+
+<guidelines>
+
+## What This File Captures
+
+**Decisions = Choices + Rationale**
+
+This template captures WHY decisions were made, not just WHAT was built. SUMMARY.md captures what was built. DECISIONS.md captures why it was built that way.
+
+Decisions help future milestones by:
+- Explaining why certain approaches were chosen
+- Documenting rejected alternatives
+- Preserving constraints that influenced choices
+- Providing context for "why is it this way?" questions
+
+## Categories Explained
+
+| Category | Content |
+|----------|---------|
+| **Technical Stack** | Libraries, frameworks, versions, tools |
+| **Architecture** | System structure, module boundaries, patterns |
+| **Data Model** | Schema, relationships, storage approach |
+| **API Design** | Endpoints, auth, errors, response format |
+| **UI/UX** | Components, layouts, interactions |
+| **Security** | Auth, authorization, data protection |
+| **Performance** | Caching, optimization, loading patterns |
+
+## Usage Rules
+
+**Remove empty categories.** If no Security decisions were made, don't include the Security section.
+
+**Keep entries concise.** Decision in 5-10 words. Rationale in 10-20 words.
+
+**Include phase number.** Helps trace when decisions were made.
+
+## Good vs Bad Entries
+
+**Good decision entries:**
+- "Use jose over jsonwebtoken | Better TypeScript support, actively maintained | 2"
+- "Flat folder structure | Avoids premature abstraction, easier navigation | 1"
+- "Server actions over API routes | Simpler data mutations for forms | 3"
+- "Tailwind over styled-components | Team familiarity, smaller bundle | 1"
+
+**Bad decision entries:**
+- "Use React | — | 1" (no rationale)
+- "Implemented authentication | Users can log in | 2" (not a decision, just work done)
+- "Added tests | Testing is important | 3" (obvious, no real decision)
+
+## Sources Appendix
+
+The Sources section documents which files were consolidated from each phase:
+
+```markdown
+| Phase | Files Found |
+|-------|-------------|
+| 1 | PLAN.md, RESEARCH.md |
+| 2 | PLAN.md, CONTEXT.md, DESIGN.md |
+| 3 | PLAN.md |
+| 4 | PLAN.md, RESEARCH.md, DESIGN.md |
+```
+
+This helps understand which phases had dedicated research, design, or context discussion.
+
+</guidelines>