kyro-ai 3.2.0

package/skills/sprint-forge/assets/helpers/sprint-generator.md

@@ -0,0 +1,145 @@
+# Sprint Generator
+
+This helper defines the step-by-step algorithm for generating a sprint from its inputs.
+
+---
+
+## Inputs
+
+Every sprint generation requires these inputs:
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Roadmap sprint section | `ROADMAP.md` → Sprint {N} definition | Yes |
+| Previous sprint | `phases/SPRINT-{N-1}-*.md` → Retro, Recommendations, Debt table | Yes (except Sprint 1) |
+| Finding file(s) | `findings/{NN}-*.md` → corresponding to this sprint's focus | Yes |
+| User overrides | Direct user instructions (priority changes, scope adjustments) | No |
+
+---
+
+## Generation Algorithm
+
+### Step 1 — Read Roadmap Section
+
+Open `ROADMAP.md` and locate the section for Sprint {N}:
+- Extract: title, focus, type, version target, suggested phases, dependencies
+- Verify dependencies are met (previous sprints completed)
+
+### Step 2 — Read Previous Sprint (Skip for Sprint 1)
+
+Open the previous sprint file and extract:
+- **Retro**: What went well, what didn't, surprises
+- **Recommendations for Sprint N**: Numbered list of recommendations
+- **Accumulated Debt Table**: Full table with all items and statuses
+
+### Step 3 — Read Finding File(s)
+
+Open the finding file(s) corresponding to this sprint:
+- Extract: summary, details, severity, affected files, recommendations
+- These become the primary source of tasks for the sprint
+
+### Step 4 — Build Disposition of Recommendations
+
+For Sprint 2+, create the Disposition table. For EACH recommendation from Sprint N-1:
+
+| # | Recommendation | Action | Where | Justification |
+|---|---------------|--------|-------|---------------|
+| {n} | {text} | {action} | {location} | {why} |
+
+**Action options**:
+- **Incorporated**: This recommendation becomes a task in the current sprint. Specify which phase and task.
+- **Deferred**: Postponed to a future sprint. Specify target sprint and justify why.
+- **Resolved**: Already addressed by intervening work. Explain when and how.
+- **N/A**: No longer applicable due to changed circumstances. Explain why.
+- **Converted to Phase**: Recommendation was significant enough to become an entire phase (not just a task). Specify which phase.
+
+**Rule**: Every recommendation MUST appear in this table. No recommendation can be silently dropped.
+
+### Step 5 — Build Phases
+
+Assemble the sprint's phases from three sources:
+
+1. **Roadmap-suggested phases**: The phases defined in the roadmap for this sprint. These are the starting point.
+2. **Recommendation phases**: If incorporated recommendations don't fit into existing phases, create new phases for them.
+3. **Debt phases**: If debt items target this sprint, create a phase to address them (or integrate into existing phases).
+
+For each phase:
+- Define a clear objective
+- List tasks with:
+  - Checkbox `[ ]`
+  - Task ID (T{phase}.{task}, e.g., T1.1, T1.2, T2.1)
+  - Description
+  - Affected files (if known from findings)
+  - Verification criteria
+
+### Step 6 — Copy and Update Debt Table
+
+1. Copy the FULL debt table from Sprint N-1 (or start empty for Sprint 1)
+2. Add new debt items discovered in the finding file analysis
+3. Update status for items targeting this sprint: `open` → `in-progress`
+4. Follow all rules from [debt-tracker.md](debt-tracker.md)
+
+### Step 7 — Write Definition of Done
+
+Create a checklist of completion criteria:
+- All phase tasks completed or explicitly skipped
+- Emergent phase tasks completed (will be empty at generation time)
+- Debt table updated
+- Retro filled
+- Recommendations documented
+- Re-entry prompts updated
+- Any project-specific criteria (e.g., "all tests pass", "pub.dev score maintained")
+
+### Step 8 — Leave Retro and Recommendations Empty
+
+The Retro and Recommendations sections are filled at sprint CLOSE, not during generation. Leave them with placeholder markers.
+
+### Step 9 — Write Sprint File
+
+Save to: `{sprints_dir}/SPRINT-{N}-{slug}.md`
+
+Where `{slug}` is a short descriptive slug derived from the sprint's focus (e.g., `architecture-cleanup`, `api-surface`, `component-quality`).
+
+---
+
+## Sprint Numbering
+
+- Sequential: Sprint 1, Sprint 2, Sprint 3, ...
+- No gaps: If Sprint 3 is removed from the roadmap, Sprint 4 does NOT become Sprint 3
+- Files: `SPRINT-{N}-{slug}.md`
+
+---
+
+## Emergent Phases
+
+Emergent phases are added during EXECUTION, not during generation. However, the sprint template includes a placeholder section for them.
+
+During execution, if new work is discovered:
+1. Add an "Emergent Phase" section after the planned phases
+2. Mark it clearly with the reason for emergence
+3. Give tasks IDs using `TE.{n}` format (T for Task, E for Emergent)
+4. Update the DoD to include emergent tasks
+
+### Findings Consolidation
+
+Before closing the sprint, consolidate all discoveries into a summary table. This is a recommended closing phase that captures institutional knowledge:
+
+1. Add a "Findings Consolidation" section after the last phase (planned or emergent)
+2. Create a summary table with columns: `#`, `Finding`, `Origin Phase`, `Impact`, `Action Taken`
+3. Include every significant discovery, not just those that generated tasks
+4. This table becomes a quick-reference for future sprints and stakeholders
+
+---
+
+## Validation Checklist
+
+Before writing the sprint file, verify:
+
+- [ ] Roadmap section for this sprint has been read
+- [ ] Previous sprint's retro, recommendations, and debt table have been read (Sprint 2+)
+- [ ] Finding file(s) have been read
+- [ ] Disposition table covers ALL previous recommendations (Sprint 2+)
+- [ ] Phases include roadmap-suggested phases + recommendation phases + debt phases
+- [ ] Debt table is copied in full from previous sprint
+- [ ] Definition of Done is specific and verifiable
+- [ ] Retro and Recommendations sections are empty (to be filled at close)

package/skills/sprint-forge/assets/modes/INIT.md

@@ -0,0 +1,204 @@
+# INIT Mode — Analysis, Roadmap & Scaffolding
+
+This mode performs deep analysis of a project, generates findings, creates an adaptive roadmap, scaffolds the working directory, and generates re-entry prompts.
+
+---
+
+## When This Mode Activates
+
+| EN Signals | ES Signals |
+|-----------|-----------|
+| "analyze", "audit", "start project", "create roadmap", "analyze codebase" | "analiza", "audita", "inicia proyecto", "crea roadmap", "analiza el codebase" |
+
+---
+
+## Prerequisites
+
+- Access to the codebase (local path or repository)
+- No previous kyro-ai work for this project (if resuming, use SPRINT or STATUS mode)
+
+---
+
+## Workflow
+
+### Step 1 — Detect Work Type
+
+Determine the type of work from the user's request:
+
+| Work Type | Signals |
+|-----------|---------|
+| Audit / Refactor | "analyze", "audit", "refactor", "review the codebase" |
+| New Feature | "add feature", "implement", "build" |
+| Bugfix | "fix", "broken", "error", "regression" |
+| New Project | "start from scratch", "new project", "create project" |
+| Tech Debt | "clean up", "deprecated", "reduce debt", "missing tests" |
+
+**Reference**: See [analysis-guide.md](../helpers/analysis-guide.md) for detailed guidance per work type.
+
+If the work type is ambiguous, ask the user:
+
+> "Is this an audit/refactor, a new feature, a bugfix, a new project, or tech debt cleanup?"
+
+### Step 2 — Resolve Configuration
+
+Gather or detect the following configuration:
+
+| Config | How to Resolve |
+|--------|---------------|
+| **Scope** | Ask the user. A short kebab-case name for the work topic (e.g., `oauth-implementation`, `ui-redesign`, `q2-growth`). NOT the repo name — the repo is already `{cwd}`. |
+| **Codebase Path** | The absolute path to the codebase. Usually the current working directory. |
+| **Sprint Output Dir** | `{output_kyro_dir}/phases/` (automatic, resolved below) |
+
+**Resolve `{output_kyro_dir}`** — ask the user:
+
+> "Where should I save kyro-ai documents for **{scope}**?
+>
+> 1. **Default** (Recommended) — `.agents/kyro/scopes/{scope}/`
+> 2. **Custom path** — provide your preferred directory"
+
+Set `{output_kyro_dir}` based on the choice. This path will be embedded in `README.md` and `RE-ENTRY-PROMPTS.md` — those are the only sources of truth. No other persistence needed.
+
+Confirm with the user:
+
+> **Scope**: {scope}
+> **Codebase**: `{codebase_path}`
+> **Output**: `{output_kyro_dir}`
+>
+> Proceed with this configuration?
+
+### Step 3 — Deep Analysis
+
+Perform thorough analysis based on the work type. This is the most critical step.
+
+**Strategy**:
+1. Use the **Explore agent** (Task tool with subagent_type=Explore) for broad codebase exploration
+2. Use **Glob** to find files by pattern
+3. Use **Grep** to search for specific patterns
+4. Use **Read** to examine specific files in detail
+
+**Analysis depth depends on work type**:
+- **Audit/Refactor**: Explore the entire codebase. Every directory, every major file. Identify all areas of concern.
+- **New Feature**: Focus on the integration points. Understand what exists and what gaps need filling.
+- **Bugfix**: Trace the bug path. Reproduce, identify root cause, assess blast radius.
+- **New Project**: Research requirements, comparable solutions, stack decisions.
+- **Tech Debt**: Scan for debt indicators across the codebase.
+
+**Reference**: See [analysis-guide.md](../helpers/analysis-guide.md) for the complete analysis strategy.
+
+**Key Principle**: The analysis determines the structure. Do NOT start with a fixed list of categories. Let the project tell you what matters.
+
+### Step 4 — Generate Findings
+
+Write each distinct finding as a separate file:
+
+**Location**: `{output_kyro_dir}/findings/`
+
+**Naming**: `NN-descriptive-slug.md` (e.g., `01-architecture-issues.md`)
+
+**Content per file**: YAML frontmatter properties (following the template in analysis-guide.md) + Summary, severity, details with code examples, affected files, recommendations.
+
+**Number of findings**: VARIABLE. Determined entirely by what the analysis reveals:
+- Small project: 2-4 findings
+- Medium refactor: 5-8 findings
+- Major audit: 10-20+ findings
+
+**Reference**: See [analysis-guide.md](../helpers/analysis-guide.md) → Step 3 for the finding file format.
+
+### Step 5 — Create Roadmap
+
+Using the [ROADMAP.md template](../templates/ROADMAP.md), create the adaptive roadmap:
+
+1. Fill in project paths (codebase, output dir, findings, phases)
+2. Map each finding to a suggested sprint:
+   - Finding 01 → Sprint 1 (usually, but not always)
+   - Related findings may be grouped into a single sprint
+   - Large findings may be split across multiple sprints
+3. Define sprint dependencies (which sprints must complete before others)
+4. For each sprint, define:
+   - Title and focus
+   - Source finding file(s)
+   - Version target (if applicable)
+   - Type (audit/refactor/feature/bugfix/debt)
+   - Suggested phases (2-5 phases per sprint)
+5. Fill in the Sprint Summary table
+6. Write the dependency map
+
+**Location**: `{output_kyro_dir}/ROADMAP.md`
+
+### Step 6 — Scaffold Working Directory
+
+Create the full directory structure:
+
+```
+{output_kyro_dir}/
+├── README.md              ← From PROJECT-README.md template
+├── ROADMAP.md             ← Created in Step 5
+├── RE-ENTRY-PROMPTS.md    ← Created in Step 7
+├── findings/              ← Created in Step 4
+│   ├── 01-*.md
+│   ├── 02-*.md
+│   └── ...
+└── phases/               ← Empty directory, sprints created later
+```
+
+**README.md**: Use the [PROJECT-README.md template](../templates/PROJECT-README.md). Fill in the frontmatter properties with actual values, then fill in:
+- Project name, type, date
+- Description of the work
+- All absolute paths
+- Baseline metrics (if applicable)
+- Initial sprint map from the roadmap
+
+### Step 7 — Generate Re-entry Prompts
+
+Using the [reentry-generator.md](../helpers/reentry-generator.md) helper:
+
+1. Use the [REENTRY-PROMPTS.md template](../templates/REENTRY-PROMPTS.md)
+2. Fill in all template variables with actual values:
+   - `{scope}`, `{codebase_path}`, `{output_kyro_dir}`
+   - `{current_sprint}` = 1 (no sprints yet)
+   - Sprint 1 finding file path
+3. Generate all 4 scenario prompts with real paths
+4. Write to `{output_kyro_dir}/RE-ENTRY-PROMPTS.md`
+
+## Output Summary
+
+At the end of INIT, present a summary:
+
+```
+## INIT Complete
+
+**Scope**: {scope}
+**Type**: {work_type}
+**Findings**: {N} files in findings/
+**Sprints Planned**: {M} sprints in roadmap
+**Files Created**:
+  - {output_kyro_dir}/README.md
+  - {output_kyro_dir}/ROADMAP.md
+  - {output_kyro_dir}/RE-ENTRY-PROMPTS.md
+  - {output_kyro_dir}/findings/01-{slug}.md
+  - {output_kyro_dir}/findings/02-{slug}.md
+  - ...
+
+**Next Step**: Generate Sprint 1 using `/kyro:forge` or copy the re-entry prompt from RE-ENTRY-PROMPTS.md → Scenario 1.
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Codebase path not found | Ask user for the correct path |
+| Output directory already exists | Ask user: overwrite, use different name, or resume |
+| No meaningful findings | Inform user — the codebase may be in good shape. Generate a minimal roadmap with maintenance sprints. |
+| Analysis scope too large | Break into phases. Analyze the most critical areas first, note others as "needs deeper analysis" finding. |
+
+---
+
+## References
+
+- [analysis-guide.md](../helpers/analysis-guide.md) — Analysis strategy per work type
+- [ROADMAP.md template](../templates/ROADMAP.md) — Roadmap structure
+- [PROJECT-README.md template](../templates/PROJECT-README.md) — Project README structure
+- [REENTRY-PROMPTS.md template](../templates/REENTRY-PROMPTS.md) — Re-entry prompts structure
+- [reentry-generator.md](../helpers/reentry-generator.md) — How to generate re-entry prompts

package/skills/sprint-forge/assets/modes/SPRINT.md

@@ -0,0 +1,253 @@
+# SPRINT Mode — Generate & Execute Sprints
+
+This mode generates the next sprint from roadmap + previous sprint + debt, and optionally executes it task by task.
+
+---
+
+## When This Mode Activates
+
+| EN Signals | ES Signals |
+|-----------|-----------|
+| "generate sprint", "next sprint", "execute sprint", "run sprint", "continue sprint" | "genera sprint", "siguiente sprint", "ejecuta sprint", "corre sprint", "continúa sprint" |
+
+---
+
+## Sub-Modes
+
+| Sub-Mode | Trigger | What Happens |
+|----------|---------|--------------|
+| **GENERATE** | "generate", "create", default when sprint file doesn't exist | Creates the sprint document only |
+| **EXECUTE** | "execute", "run", "implement", sprint file already exists | Implements tasks from an existing sprint |
+| **GENERATE+EXECUTE** | "generate and execute", "do the next sprint" | Generates then immediately executes |
+
+If ambiguous, ask:
+
+> "Should I **generate** the sprint document, **execute** an existing sprint, or **both**?"
+
+---
+
+## GENERATE Workflow
+
+### Step 0 — Locate Output Directory
+
+Determine `{output_kyro_dir}` before reading any sprint files:
+
+1. **Re-entry prompt paths** — If the user's message contains absolute file paths (e.g. `/Users/.../ROADMAP.md`), extract `{output_kyro_dir}` from those paths. This is the most reliable source.
+2. **Explicit path** — If the user mentions a path directly, use it.
+3. **Auto-discover** — Scan `{cwd}/.agents/kyro/scopes/`:
+   - Single directory found → use it
+   - Multiple directories → ask: "Which project? Found: {list}"
+4. **Ask** — If none of the above: "Where are your kyro-ai documents? (e.g. `.agents/kyro/scopes/my-project/`)"
+
+Once resolved, all subsequent steps use `{output_kyro_dir}` as the base for all file paths.
+
+### Step 1 — Determine Sprint Number
+
+1. Read `ROADMAP.md` to understand the planned sprints
+2. Scan `phases/` directory for existing sprint files
+3. The next sprint number = highest existing sprint + 1
+4. If no sprints exist, start with Sprint 1
+
+### Step 2 — Gather Inputs
+
+Read the required inputs as defined in [sprint-generator.md](../helpers/sprint-generator.md):
+
+1. **Roadmap section**: Open `ROADMAP.md`, locate Sprint {N} definition
+   - Extract: title, focus, type, version target, suggested phases
+2. **Previous sprint** (Sprint 2+): Open `phases/SPRINT-{N-1}-*.md`
+   - Extract: Retro, Recommendations, Accumulated Debt Table
+3. **Finding file(s)**: Open the finding file(s) mapped to this sprint in the roadmap
+   - Extract: summary, details, affected files, recommendations
+
+### Step 3 — Build Disposition Table (Sprint 2+)
+
+For every recommendation from Sprint N-1, determine what happens to it:
+
+| # | Recommendation | Action | Where | Justification |
+|---|---------------|--------|-------|---------------|
+| 1 | {text from sprint N-1} | Incorporated | Phase 2, T2.3 | Directly addresses API consistency |
+| 2 | {text from sprint N-1} | Deferred | Sprint 5 | Requires schema migration first |
+| 3 | {text from sprint N-1} | N/A | — | Fixed by Sprint 2 emergent phase |
+| 4 | {text from sprint N-1} | Converted to Phase | Phase 4 | Significant enough to warrant its own phase |
+
+**Every recommendation MUST appear in this table.** No exceptions.
+
+**Action options**: Incorporated, Deferred, Resolved, N/A, **Converted to Phase** (when a recommendation becomes an entire phase, not just a task).
+
+**Reference**: See [sprint-generator.md](../helpers/sprint-generator.md) → Step 4 for action options.
+
+### Step 4 — Build Phases
+
+Assemble phases from three sources:
+
+1. **Roadmap-suggested phases**: Starting point from the roadmap
+2. **Recommendation phases**: Incorporated recommendations that need their own phase
+3. **Debt phases**: Debt items targeting this sprint
+
+For each phase:
+- **Objective**: Clear statement of what the phase accomplishes
+- **Tasks**: List with checkboxes, task IDs (T{phase}.{task}), descriptions, file paths, verification criteria
+
+**Reference**: See [sprint-generator.md](../helpers/sprint-generator.md) → Step 5 for phase assembly rules.
+
+### Step 5 — Assemble Sprint Document
+
+Use the [SPRINT.md template](../templates/SPRINT.md):
+
+1. Fill frontmatter properties with actual values (title, date, project, sprint number, previous/next doc links, related findings)
+2. Fill metadata: source finding, previous sprint, version target, type, carry-over count
+3. Write sprint objective
+4. Write Disposition table (Sprint 2+)
+5. Write phases with tasks
+6. Copy debt table from previous sprint + add new items
+7. Write Definition of Done
+8. Leave Retro and Recommendations sections EMPTY
+
+**Reference**: See [debt-tracker.md](../helpers/debt-tracker.md) for debt table rules.
+
+### Step 6 — Write Sprint File
+
+Save to: `{sprints_dir}/SPRINT-{N}-{slug}.md`
+
+The slug is derived from the sprint's focus area (e.g., `architecture-cleanup`, `api-consistency`).
+
+---
+
+## EXECUTE Workflow
+
+### Step 7 — Read Sprint
+
+Load the sprint file to execute. Verify it has:
+- Phases with tasks
+- Debt table
+- Definition of Done
+
+**Fill execution metadata**: Set `Execution Date` to today's date and `Executed By` to the executor's name in the sprint header. Also update the frontmatter `updated` field to today's date. These fields track who executed the sprint and when.
+
+### Step 8 — Execute Task by Task
+
+For each task in each phase:
+
+1. **Mark in-progress**: Change `[ ]` to `[~]`
+2. **Do the work**:
+   - Read relevant files
+   - Write/modify code as needed
+   - Run verification commands
+   - Test changes
+3. **Mark done**: Change `[~]` to `[x]`
+4. **Or mark blocked**: Change `[~]` to `[!]` with explanation
+5. **Or mark carry-over**: Change `[~]` to `[>]` — when a task cannot be completed in this sprint but is not blocked. It will be carried over to the next sprint.
+
+**Document evidence inline**: For each task, fill the `Evidence` field with concrete proof of work — trace logs, before/after snapshots, tables of affected items, verification marks. Evidence is not optional; it makes the sprint auditable.
+
+**Execution order**: Process phases in order (Phase 1 → Phase 2 → ...). Within a phase, process tasks in order unless dependencies require different ordering.
+
+**Persistence rule — checkpoint per phase**: After completing all tasks in a phase, write the sprint file to disk with all status updates (`[x]`, `[!]`, `[>]`) and evidence for that phase. This ensures progress survives unexpected interruptions (agent crash, session timeout, context overflow) without disrupting task-to-task flow within a phase. Do NOT write the file after every individual task — that fragments the agent's focus and wastes I/O. Do NOT defer all writes to sprint close — that risks losing all progress tracking on failure.
+
+**Code quality**: Write production-quality code. Follow existing project patterns. Do not introduce new patterns without justification.
+
+### Step 9 — Handle Emergent Work
+
+During execution, you may discover work not covered by the plan. This is expected.
+
+**When to add an Emergent Phase**:
+- Found a bug that must be fixed before continuing
+- Discovered a dependency that was not in the analysis
+- A task reveals additional scope that cannot be deferred
+
+**How to add**:
+1. Add an "Emergent Phase" section in the sprint document (after planned phases)
+2. Include: phase name, reason for emergence, tasks with IDs (TE.1, TE.2, ...)
+3. Update Definition of Done to include emergent tasks
+
+**Rule**: Do not add emergent phases for nice-to-haves. Only for work that is necessary to meet the sprint objective or that would create debt if deferred.
+
+### Step 10 — Close Sprint
+
+When all tasks are done (or explicitly skipped/blocked/carried-over):
+
+**10a. Consolidate Findings**: Before filling the retro, complete the **Findings Consolidation** table. Review all phases (planned and emergent) and list every significant discovery with its origin, impact, and action taken. This creates an auditable trail of what was learned.
+
+1. **Fill Retro section**:
+   - What Went Well: Things that worked as expected or better
+   - What Didn't Go Well: Challenges, blockers, things that took longer
+   - Surprises: Unexpected findings or outcomes
+   - **New Technical Debt Detected**: List new debt items discovered during execution, referencing their D{n} numbers from the Accumulated Debt table
+
+2. **Fill Recommendations for Sprint N+1**:
+   - Numbered list of specific, actionable recommendations
+   - These become formal input for the next sprint's Disposition table
+   - Include both technical and process recommendations
+
+3. **Update Debt Table**:
+   - Mark resolved items: Status → `resolved`, fill "Resolved In"
+   - Add new items discovered during execution
+   - Update deferred items if timelines changed
+   - Follow all rules from [debt-tracker.md](../helpers/debt-tracker.md)
+
+4. **Update Frontmatter**:
+   - Set `updated` to today's date
+   - Set `status` to `"completed"` (or `"active"` if carry-overs exist)
+   - Set `progress` to final completion percentage (0-100)
+   - Append changelog entry: `{"version": "1.1", "date": "{today}", "changes": ["Sprint completed"]}`
+
+5. **Verify Definition of Done**:
+   - Check every DoD item
+   - Mark as complete or document why it's not
+
+### Step 11 — Update Re-entry Prompts
+
+After sprint execution:
+
+1. Open `{output_kyro_dir}/RE-ENTRY-PROMPTS.md`
+2. Update current sprint number
+3. Update file references (last sprint, next finding)
+4. Update Quick Reference table with new sprint status
+5. Update "Last updated" date
+
+**Reference**: See [reentry-generator.md](../helpers/reentry-generator.md) for update rules.
+
+### Step 12 — Update Roadmap (If Needed)
+
+If execution revealed that the roadmap needs adjustment:
+
+- A planned sprint no longer makes sense → remove or modify it
+- A new sprint is needed → add it to the roadmap
+- Sprint dependencies changed → update the dependency map
+- Phase suggestions for future sprints should change → update them
+
+**This is the ADAPTIVE principle**: The roadmap serves execution, not the reverse.
+
+---
+
+## Critical Rules for Sprint Mode
+
+1. **One sprint at a time** — NEVER generate Sprint N+1 before Sprint N is complete
+2. **Disposition is mandatory** — Every recommendation from Sprint N-1 must be in the Disposition table
+3. **Emergent phases are welcome** — But only for necessary work, not nice-to-haves
+4. **Debt table is inherited completely** — Never drop items, never reset the table
+5. **Re-entry prompts must be updated** — Every sprint execution ends with a prompt update
+6. **Retro is honest** — Don't sugarcoat. Document real challenges and surprises.
+7. **Recommendations are specific** — "Improve tests" is not a recommendation. "Add unit tests for the auth middleware error paths in auth.ts:45-80" is.
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No roadmap found | INIT mode must be run first. Inform user. |
+| Previous sprint not found | Check if sprint numbering is correct. If Sprint 1, this is expected. |
+| Finding file not found | Check roadmap mapping. The file may have been renamed or the mapping may be wrong. |
+| All tasks blocked | Document blockers in retro, close sprint as incomplete, recommend resolution in Sprint N+1. |
+| Sprint file already exists | Ask user: overwrite, resume execution, or skip to next sprint. |
+
+---
+
+## References
+
+- [sprint-generator.md](../helpers/sprint-generator.md) — Sprint generation algorithm
+- [debt-tracker.md](../helpers/debt-tracker.md) — Debt table rules
+- [reentry-generator.md](../helpers/reentry-generator.md) — Re-entry prompt updates
+- [SPRINT.md template](../templates/SPRINT.md) — Sprint document structure
+