hatch3r 1.2.0 → 1.3.0

package/agents/modes/complexity-risk.md

@@ -0,0 +1,40 @@
+---
+id: researcher-mode-complexity-risk
+type: mode
+description: Identify code complexity hotspots and mutation-prone areas for test prioritization.
+parent: hatch3r-researcher
+---
+### Mode: `complexity-risk`
+
+Identify code complexity hotspots, mutation-prone areas, and error handling coverage to prioritize where tests will have the highest impact. Used by `hatch3r-test-plan` to focus testing effort on the riskiest code.
+
+**Output structure:**
+
+```markdown
+## Complexity & Risk Analysis
+
+### Complexity Hotspots
+| # | File / Function | Complexity Signal | Severity | Current Test Coverage | Testing Priority |
+|---|----------------|------------------|----------|---------------------|-----------------|
+| 1 | {file:function} | {high cyclomatic complexity / deep nesting / large function / many branches} | High/Med/Low | Covered/Partial/None | P0/P1/P2/P3 |
+
+### Mutation-Prone Areas
+| # | Module / File | Why Mutation-Prone | Mutation Score (est.) | Recommended Action |
+|---|-------------|-------------------|---------------------|-------------------|
+| 1 | {path} | {many conditionals / complex state transitions / arithmetic logic} | {estimated or measured}% | {add assertions / property tests / mutation testing} |
+
+### Error Handling Coverage
+| # | Error Path | File(s) | Currently Tested? | Failure Impact | Priority |
+|---|-----------|---------|------------------|---------------|----------|
+| 1 | {error scenario} | {file paths} | Yes/No/Partial | {what happens if this error path is wrong} | P0/P1/P2/P3 |
+
+### Recommended Testing Depth
+| Module / Area | Recommended Depth | Rationale |
+|---------------|------------------|-----------|
+| {module} | Thorough (unit + integration + property) / Standard (unit + integration) / Light (unit only) | {complexity, risk, and coverage factors} |
+```
+
+**Depth scaling:**
+- **quick**: Top 5 complexity hotspots + recommended testing depth table only.
+- **standard**: Full hotspots (top 10), mutation-prone areas, error handling coverage (top 5), and recommended depth.
+- **deep**: All sections exhaustively. Cross-reference mutation targets from `hatch3r-testing` rule (70% critical, 60% general). Include estimated mutation scores and specific assertion gaps.

package/agents/modes/coverage-analysis.md

@@ -0,0 +1,44 @@
+---
+id: researcher-mode-coverage-analysis
+type: mode
+description: Map existing test coverage, identify gaps, and surface critical untested paths.
+parent: hatch3r-researcher
+---
+### Mode: `coverage-analysis`
+
+Map existing test coverage, identify gaps, and surface critical untested paths. Used by `hatch3r-test-plan` to understand the current testing baseline before planning new tests.
+
+**Output structure:**
+
+```markdown
+## Coverage Analysis
+
+### Existing Test Inventory
+| Test File | Type | Module / Area Covered | Test Count | Framework |
+|-----------|------|----------------------|-----------|-----------|
+| {path} | Unit/Integration/E2E | {what it tests} | {approx count} | {vitest/jest/playwright/etc.} |
+
+### Coverage Gaps
+| Module / Area | Statement % | Branch % | Function % | Gap Severity | Notes |
+|---------------|------------|----------|-----------|-------------|-------|
+| {module} | {current or "unknown"} | {current or "unknown"} | {current or "unknown"} | Critical/High/Med/Low | {why this gap matters} |
+
+### Critical Untested Paths
+| # | Code Path | File(s) | Risk if Untested | Recommended Test Type |
+|---|-----------|---------|-----------------|---------------------|
+| 1 | {description of untested path} | {file paths} | {what could go wrong} | Unit/Integration/E2E/Property |
+
+### Coverage Metrics Summary
+| Metric | Current | Target (hatch3r-testing rule) | Gap |
+|--------|---------|-------------------------------|-----|
+| Statement coverage | {N}% or unknown | 80% (90% critical) | {delta} |
+| Branch coverage | {N}% or unknown | 70% (85% critical) | {delta} |
+| Function coverage | {N}% or unknown | 80% | {delta} |
+| Mutation score | {N}% or unknown | 70% critical / 60% general | {delta} |
+| Flaky test rate | {N}% or unknown | < 0.5% | {delta} |
+```
+
+**Depth scaling:**
+- **quick**: Test file inventory + coverage metrics summary only. Skip gap analysis and untested paths.
+- **standard**: Full inventory, coverage gaps, critical untested paths (top 5), and metrics summary.
+- **deep**: All sections with exhaustive gap analysis, all untested paths enumerated, cross-reference against `hatch3r-testing` rule thresholds, and flaky test inventory from quarantine directory.

package/agents/modes/current-state.md

@@ -0,0 +1,52 @@
+---
+id: researcher-mode-current-state
+type: mode
+description: Map the current state of code being analyzed — complexity, coupling, cohesion, coverage.
+parent: hatch3r-researcher
+---
+### Mode: `current-state`
+
+Map the current state of the code being analyzed. Measure complexity, coupling, cohesion, test coverage, and code quality. Identify the specific problems that motivate the change.
+
+**Dimension-specific focus** (when provided):
+- **Structural:** Emphasize coupling, cohesion, module boundaries, dead code
+- **Logical:** Emphasize behavior contracts, data flows, state management, business rules
+- **Visual:** Emphasize component hierarchy, design token usage, accessibility compliance, responsive patterns
+- **Migration:** Emphasize framework/library API surface, adapter boundaries, compatibility layers
+
+**Output structure:**
+
+```markdown
+## Current State Analysis
+
+### Module Map
+| Module / Component | Files | Lines of Code | Responsibility | Coupling |
+|-------------------|-------|---------------|---------------|----------|
+| {module} | {count} | {approx} | {what it does} | {what it depends on and what depends on it} |
+
+### Complexity Metrics
+| File / Function | Complexity Signal | Severity | Notes |
+|----------------|------------------|----------|-------|
+| {file:function} | {high cyclomatic complexity / deep nesting / large function / etc.} | High/Med/Low | {context} |
+
+### Code Smells
+| # | Smell | Location | Description | Impact on Maintainability |
+|---|-------|----------|-------------|--------------------------|
+| 1 | {smell type} | {file:line range} | {description} | {how it hurts} |
+
+### Dependency Graph
+| Component | Depends On | Depended On By | Coupling Type |
+|-----------|-----------|---------------|---------------|
+| {component} | {dependencies} | {dependents} | Hard/Soft/Circular |
+
+### Test Coverage
+| Area | Unit Tests | Integration Tests | Coverage Level | Safety for Refactoring |
+|------|-----------|------------------|---------------|----------------------|
+| {area} | {count / exists / missing} | {count / exists / missing} | High/Med/Low | Safe/Needs tests first |
+
+### Pattern Inventory
+- **{pattern}**: {where used} — {whether to keep, replace, or extend}
+
+### Current State Summary
+{2-3 paragraphs describing the state of the code, why it needs changing, and what the key structural problems are}
+```

package/agents/modes/feature-design.md

@@ -0,0 +1,39 @@
+---
+id: researcher-mode-feature-design
+type: mode
+description: Break the subject down into implementable sub-tasks with user stories and acceptance criteria.
+parent: hatch3r-researcher
+---
+### Mode: `feature-design`
+
+Break the subject down into implementable sub-tasks with user stories, acceptance criteria, edge cases, and effort estimates.
+
+**Output structure:**
+
+```markdown
+## Feature Breakdown
+
+### Sub-Tasks
+| # | Sub-Task | User Story | Acceptance Criteria | Effort | Dependencies |
+|---|----------|-----------|---------------------|--------|--------------|
+| 1 | {title} | As a {persona}, I want {goal} so that {benefit} | - [ ] {criterion} | S/M/L/XL | {deps} |
+
+### Edge Cases
+| # | Scenario | Expected Behavior | Priority |
+|---|----------|-------------------|----------|
+| 1 | {edge case} | {how the system should handle it} | Must/Should/Nice |
+
+### UX Considerations
+- **{consideration}**: {recommendation and rationale}
+
+### Effort Summary
+| Metric | Value |
+|--------|-------|
+| Total sub-tasks | {N} |
+| Estimated total effort | {S/M/L/XL — map to rough days} |
+| Parallelizable tasks | {list task numbers that can run concurrently} |
+| Critical path | task {N} → task {M} → task {P} |
+
+### Suggested Priority
+{P0/P1/P2/P3}: {rationale for this priority level}
+```

package/agents/modes/impact-analysis.md

@@ -0,0 +1,45 @@
+---
+id: researcher-mode-impact-analysis
+type: mode
+description: Map the blast radius of an issue across flows, modules, data, and users.
+parent: hatch3r-researcher
+---
+### Mode: `impact-analysis`
+
+Map the blast radius. Identify all flows, modules, data, and users affected. Find related issues or symptoms that might share the same cause. Assess data integrity risk and downstream consumers.
+
+**Output structure:**
+
+```markdown
+## Impact Assessment
+
+### Affected Flows
+| Flow | Impact | Users Affected | Data at Risk? |
+|------|--------|---------------|---------------|
+| {user flow or system process} | {how it is affected} | {persona or segment} | Yes/No — {details} |
+
+### Affected Modules
+| Module / Area | How Affected | Severity | Coupling |
+|---------------|-------------|----------|----------|
+| {module} | {direct failure / degraded / cascading} | Critical/High/Med/Low | Direct/Indirect |
+
+### Downstream Consumers
+| Consumer | Coupling Type | Impact | Action Needed |
+|----------|-------------|--------|--------------|
+| {module/service/user} | {direct API / import / event / data} | {none / update needed / rewrite needed} | {what to do} |
+
+### Data Integrity Risk
+| Data | Risk | Detection | Recovery |
+|------|------|-----------|----------|
+| {what data is at risk} | {corruption / loss / inconsistency} | {how to detect damage} | {how to recover} |
+
+### Related Symptoms
+| # | Symptom | Reported? | Likely Same Cause? |
+|---|---------|-----------|-------------------|
+| 1 | {other observed issue} | Yes (#{issue}) / No | Yes/Likely/Unlikely |
+
+### User-Facing Impact
+- **Severity:** {Critical/High/Med/Low}
+- **Scope:** {how many users, what percentage of traffic}
+- **Workaround available:** {yes — describe / no}
+```

package/agents/modes/library-docs.md

@@ -0,0 +1,31 @@
+---
+id: researcher-mode-library-docs
+type: mode
+description: Look up current API documentation for specific libraries via Context7 MCP.
+parent: hatch3r-researcher
+---
+### Mode: `library-docs`
+
+Look up current API documentation for specific libraries or frameworks using Context7 MCP.
+
+**Protocol:**
+1. Call `resolve-library-id` with the library name to get the Context7-compatible ID.
+2. Call `query-docs` with the resolved ID and the specific API question.
+3. Summarize findings in structured output.
+
+**Output structure:**
+
+```markdown
+## Library Documentation
+
+### {Library Name} ({version})
+| API / Function | Signature | Notes |
+|---------------|-----------|-------|
+| {API} | {signature or usage pattern} | {relevant constraints, deprecations, or gotchas} |
+
+### Key Patterns
+- {pattern}: {how to use it correctly}
+
+### Breaking Changes / Deprecations
+- {item}: {migration path}
+```

package/agents/modes/migration-path.md

@@ -0,0 +1,55 @@
+---
+id: researcher-mode-migration-path
+type: mode
+description: Design a phased execution plan with safe ordering and rollback points.
+parent: hatch3r-researcher
+---
+### Mode: `migration-path`
+
+Design a phased execution plan with safe ordering. Each phase must leave the codebase in a working state. Identify parallel lanes, rollback points, and map phases to execution skills.
+
+**Output structure:**
+
+```markdown
+## Migration Path
+
+### Phase Overview
+| Phase | Title | Scope | Depends On | Skill | Effort | Rollback Point? |
+|-------|-------|-------|-----------|-------|--------|----------------|
+| 0 | {test scaffolding} | {add missing tests before refactoring} | — | hatch3r-qa-validation | S/M | Yes |
+| 1 | {first transformation} | {what changes} | Phase 0 | hatch3r-refactor | S/M/L | Yes |
+
+### Phase Details
+
+#### Phase {N}: {Title}
+- **Goal:** {what this phase achieves}
+- **Transformations:** {list of specific changes}
+- **Files:** {list with change descriptions}
+- **Behavioral invariants:** {what must still hold after this phase}
+- **Verification:** {how to confirm the phase is successful}
+- **Rollback:** {how to revert this phase without affecting others}
+
+### Parallel Lanes
+| Lane | Phases | Why Independent |
+|------|--------|----------------|
+| A | {phase numbers} | {no shared files or interfaces} |
+| B | {phase numbers} | {no shared files or interfaces} |
+
+### Critical Path
+{phase X} → {phase Y} → {phase Z} (total: {effort estimate})
+
+### Completion Criteria
+- [ ] All phases completed and verified
+- [ ] All behavioral invariants confirmed via tests
+- [ ] No regression in existing test suite
+- [ ] Dead code from old patterns removed
+- [ ] Documentation updated (specs, ADRs)
+
+### Skill Mapping
+| Phase | Execution Skill | Why |
+|-------|----------------|-----|
+| {phase} | hatch3r-refactor | Structural code quality improvement |
+| {phase} | hatch3r-logical-refactor | Behavior or logic flow change |
+| {phase} | hatch3r-visual-refactor | UI/UX component change |
+| {phase} | hatch3r-qa-validation | Test scaffolding before refactoring |
+```

package/agents/modes/prior-art.md

@@ -0,0 +1,31 @@
+---
+id: researcher-mode-prior-art
+type: mode
+description: Research best practices, known issues, and ecosystem trends via web search.
+parent: hatch3r-researcher
+---
+### Mode: `prior-art`
+
+Research best practices, known issues, ecosystem trends, and prior art via web search. Use for novel problems, security advisories, or approaches not covered by local docs or Context7.
+
+**Output structure:**
+
+```markdown
+## Prior Art Research
+
+### Best Practices
+| # | Practice | Source | Applicability |
+|---|---------|--------|--------------|
+| 1 | {practice} | {source — blog, docs, RFC} | {how it applies to the subject} |
+
+### Known Issues / CVEs
+| # | Issue | Severity | Affected Versions | Mitigation |
+|---|-------|----------|-------------------|------------|
+| 1 | {issue or CVE} | {severity} | {versions} | {fix or workaround} |
+
+### Ecosystem Trends
+- {trend}: {relevance to the subject}
+
+### Reference Implementations
+- {project/example}: {what it demonstrates and how it's relevant}
+```

package/agents/modes/refactoring-strategy.md

@@ -0,0 +1,55 @@
+---
+id: researcher-mode-refactoring-strategy
+type: mode
+description: Design the refactoring approach with transformations, invariants, and patterns.
+parent: hatch3r-researcher
+---
+### Mode: `refactoring-strategy`
+
+Design the refactoring approach. Propose specific transformations (extract, inline, rename, restructure, migrate). Define behavioral invariants that must hold throughout. Identify patterns to follow from the existing codebase or from best practices.
+
+**Dimension-specific focus** (when provided):
+- **Structural:** Extract module, split file, reduce coupling, enforce boundaries
+- **Logical:** Behavior migration, data model evolution, API versioning, state machine redesign
+- **Visual:** Component refactoring, design token standardization, accessibility remediation, layout restructuring
+- **Migration:** Framework swap, adapter pattern, compatibility shim, incremental migration
+
+**Output structure:**
+
+```markdown
+## Refactoring Strategy
+
+### Target Architecture
+{Description of the desired end state — how the code should look after refactoring}
+
+### Transformation Plan
+| # | Transformation | Type | From → To | Invariants |
+|---|---------------|------|-----------|-----------|
+| 1 | {what to do} | Extract/Inline/Restructure/Migrate/Replace | {current} → {target} | {what must not change} |
+
+### Behavioral Invariants
+| # | Invariant | How to Verify | Current Test Coverage |
+|---|-----------|--------------|---------------------|
+| 1 | {behavior that must be preserved} | {test or assertion strategy} | Covered/Needs test |
+
+### New Patterns Introduced
+| Pattern | Where | Justification | Precedent in Codebase? |
+|---------|-------|--------------|----------------------|
+| {pattern} | {where it applies} | {why this pattern over alternatives} | Yes — {where} / No — {why new} |
+
+### Patterns Removed
+| Pattern | Where | Replacement | Migration Strategy |
+|---------|-------|-------------|-------------------|
+| {pattern being replaced} | {current locations} | {what replaces it} | {how to migrate} |
+
+### Interface Contracts
+| Interface / API | Current Contract | New Contract | Breaking? | Migration |
+|----------------|-----------------|-------------|-----------|-----------|
+| {interface} | {current shape} | {new shape or "unchanged"} | Yes/No | {strategy} |
+
+### Effort Estimate
+| Phase | Effort | Parallelizable? |
+|-------|--------|----------------|
+| {phase} | S/M/L/XL | Yes/No |
+| **Total** | {aggregate} | {parallel lanes} |
+```

package/agents/modes/regression.md

@@ -0,0 +1,45 @@
+---
+id: researcher-mode-regression
+type: mode
+description: Investigate when an issue was introduced by analyzing git history and changes.
+parent: hatch3r-researcher
+---
+### Mode: `regression`
+
+Investigate when the issue was likely introduced and what changed. Analyze git history, recent dependency updates, configuration changes, and deployment events in the affected area.
+
+**Output structure:**
+
+```markdown
+## Regression Analysis
+
+### Timeline
+| Date / Period | Change | Author | Files | Potential Link |
+|--------------|--------|--------|-------|---------------|
+| {date or range} | {commit message or change description} | {who} | {files changed} | High/Med/Low — {reasoning} |
+
+### Recent Changes in Affected Area
+| File | Last Modified | Change Summary | Suspicious? |
+|------|-------------|----------------|-------------|
+| {file path} | {date} | {what changed} | Yes/No — {why} |
+
+### Dependency Changes
+| Dependency | Previous Version | Current Version | Changelog Relevant? |
+|-----------|-----------------|----------------|---------------------|
+| {package} | {old} | {new} | Yes — {breaking change or bug fix} / No |
+
+### Configuration Changes
+| Config | Change | When | Impact |
+|--------|--------|------|--------|
+| {config file or env var} | {what changed} | {when} | {how it could cause the issue} |
+
+### Most Likely Introduction Window
+- **When:** {date range or commit range}
+- **What changed:** {description}
+- **Confidence:** High/Med/Low
+- **Bisect strategy:** {how to narrow down further if needed}
+
+### Previously Working State
+- **Last known good:** {version, commit, or date when this worked}
+- **Evidence:** {test results, user reports, or deploy logs}
+```

package/agents/modes/requirements-elicitation.md

@@ -0,0 +1,68 @@
+---
+id: researcher-mode-requirements-elicitation
+type: mode
+description: Detect ambiguities and missing requirements, generate structured questions across 10 dimensions.
+parent: hatch3r-researcher
+---
+### Mode: `requirements-elicitation`
+
+Analyze the task description against the codebase to detect ambiguities, unstated assumptions, and missing requirements. Generate structured questions for the user across 10 dimensions to resolve unknowns before implementation. Triggered by the `hatch3r-deep-context` rule based on complexity tier.
+
+**Protocol:**
+
+1. Parse the task description for vague language ("improve", "better", "proper", "handle", "support", "clean up", "fix", "update") and flag each instance.
+2. Identify unstated assumptions by comparing the task against the codebase structure — what does the task imply but not state explicitly?
+3. For each of the 10 dimensions below, determine if the task description addresses it. If not, generate a targeted question.
+4. Scan the codebase for modules that will be affected by the task. For each, check whether the task description accounts for its consumers, contracts, and side effects. Generate dependency-derived questions from gaps.
+5. Check for cross-cutting concerns triggered by the task and list them with status (addressed / unaddressed).
+
+**10 Dimensions:**
+
+1. **Data** — schema shape, data source, expected volume, validation rules, migration needs
+2. **Behavior** — success flow, error/failure flow, edge cases, concurrent access, idempotency
+3. **UI/UX** — loading states, empty states, error states, responsive behavior, accessibility, animations
+4. **Security** — auth/authz model, data sensitivity classification, input validation, rate limiting, CSRF/XSS
+5. **Performance** — expected data volume, caching strategy, pagination, lazy loading, bundle impact
+6. **Integration** — existing features this interacts with, shared state, event chains, API consumers
+7. **Migration** — existing data or behavior that changes, backward compatibility, rollback strategy
+8. **Observability** — logging requirements, metrics, error tracking, audit trail for the new behavior
+9. **Testing** — what constitutes "working", acceptance test scenarios, edge case coverage expectations
+10. **Rollout** — feature flags, phased rollout, A/B testing, rollback trigger conditions
+
+**Output structure:**
+
+```markdown
+## Requirements Elicitation
+
+### Ambiguity Detection
+| # | Term / Phrase | Context | Why It's Ambiguous | Suggested Clarification |
+|---|--------------|---------|-------------------|------------------------|
+| 1 | {vague term} | {where it appears} | {what's unclear} | {specific question} |
+
+### Dimension Probe Questions
+| # | Dimension | Question | Why This Matters | Default If Unanswered |
+|---|-----------|----------|-----------------|----------------------|
+| 1 | {dimension} | {specific question} | {what could go wrong without an answer} | {safe default the implementer would assume} |
+
+### Dependency-Derived Questions
+| # | Module / Interface | Consumers | Question |
+|---|-------------------|-----------|----------|
+| 1 | {module being changed} | {list of consumers} | {question about contract impact} |
+
+### Cross-Cutting Concern Checklist
+| Concern | Triggered? | Addressed in Task? | Action Needed |
+|---------|-----------|-------------------|--------------|
+| Authentication / Authorization | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Internationalization (i18n) | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Accessibility (a11y) | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Error Handling | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Data Validation | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Observability / Logging | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Backward Compatibility | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Feature Flags / Rollout | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+
+### Requirements Summary
+- **Resolved:** {N} dimensions fully addressed
+- **Needs clarification:** {N} questions requiring user input before implementation
+- **Safe defaults available:** {N} questions where a reasonable default exists if the user defers
+```

package/agents/modes/risk-assessment.md

@@ -0,0 +1,41 @@
+---
+id: researcher-mode-risk-assessment
+type: mode
+description: Identify risks, security implications, performance concerns, and breaking changes.
+parent: hatch3r-researcher
+---
+### Mode: `risk-assessment`
+
+Identify risks, security implications, performance concerns, breaking changes, migration needs, and common mistakes.
+
+**Output structure:**
+
+```markdown
+## Risk Assessment
+
+### Technical Risks
+| # | Risk | Likelihood | Impact | Mitigation |
+|---|------|-----------|--------|------------|
+| 1 | {risk} | High/Med/Low | High/Med/Low | {strategy} |
+
+### Security Implications
+| # | Concern | Severity | Mitigation |
+|---|---------|----------|------------|
+| 1 | {concern} | Critical/High/Med/Low | {strategy} |
+
+### Performance Concerns
+| # | Concern | When It Matters | Mitigation |
+|---|---------|----------------|------------|
+| 1 | {concern} | {threshold or condition} | {strategy} |
+
+### Breaking Changes
+| # | What Breaks | Who Is Affected | Migration Path |
+|---|------------|----------------|----------------|
+| 1 | {change} | {consumers/users} | {migration strategy} |
+
+### Common Mistakes
+- **{mistake}**: {why it's tempting} → {what to do instead}
+
+### Recommended Safeguards
+- {safeguard}: {rationale}
+```

package/agents/modes/risk-prioritization.md

@@ -0,0 +1,43 @@
+---
+id: researcher-mode-risk-prioritization
+type: mode
+description: Risk-ranked prioritization of testing effort by business impact and coverage.
+parent: hatch3r-researcher
+---
+### Mode: `risk-prioritization`
+
+Produce a risk-ranked prioritization of testing effort considering business impact, security exposure, change frequency, and current coverage. Used by `hatch3r-test-plan` to order test implementation for maximum risk reduction.
+
+**Output structure:**
+
+```markdown
+## Risk-Based Test Prioritization
+
+### Risk Matrix
+| # | Module / Area | Business Impact | Security Exposure | Change Frequency | Current Coverage | Risk Score | Test Priority |
+|---|-------------|----------------|------------------|-----------------|-----------------|-----------|--------------|
+| 1 | {module} | Critical/High/Med/Low | Critical/High/Med/Low | High/Med/Low | High/Med/Low/None | {weighted score} | P0/P1/P2/P3 |
+
+### Recommended Test Investment Order
+| Priority | Module / Area | Recommended Tests | Effort | Risk Reduction |
+|----------|-------------|------------------|--------|---------------|
+| P0 | {module} | {test types and count} | S/M/L | {what risk this eliminates} |
+| P1 | {module} | {test types and count} | S/M/L | {what risk this reduces} |
+| P2 | {module} | {test types and count} | S/M/L | {what risk this reduces} |
+| P3 | {module} | {test types and count} | S/M/L | {incremental improvement} |
+
+### Quick Wins
+| # | Test to Add | Module | Effort | Risk Reduction | Why It's a Quick Win |
+|---|-----------|--------|--------|---------------|---------------------|
+| 1 | {specific test description} | {module} | XS/S | {impact} | {already has test infra / simple boundary / high-value assertion} |
+
+### Technical Debt Tests
+| # | Debt Item | Module | Current Risk | Recommended Test | Blocks |
+|---|----------|--------|-------------|-----------------|--------|
+| 1 | {tech debt — e.g., untested legacy module, missing error handling tests} | {module} | {what could go wrong} | {test type and scope} | {what this blocks — e.g., safe refactoring, migration} |
+```
+
+**Depth scaling:**
+- **quick**: Risk matrix (top 5 modules) + quick wins only.
+- **standard**: Full risk matrix, investment order (P0-P2), quick wins, and top 3 technical debt items.
+- **deep**: All sections exhaustively. Full risk matrix with weighted scoring, complete investment order (P0-P3), all quick wins, and comprehensive technical debt test inventory.

package/agents/modes/root-cause.md

@@ -0,0 +1,39 @@
+---
+id: researcher-mode-root-cause
+type: mode
+description: Analyze the codebase for candidate root causes using static analysis patterns.
+parent: hatch3r-researcher
+---
+### Mode: `root-cause`
+
+Analyze the codebase for candidate root causes. Use static analysis patterns: off-by-one errors, race conditions, missing null checks, incorrect assumptions, stale caches, wrong operator usage, missing error handling, and anti-patterns. Rank hypotheses by likelihood.
+
+**Output structure:**
+
+```markdown
+## Root Cause Analysis
+
+### Hypotheses (Ranked by Likelihood)
+| Rank | Hypothesis | Likelihood | Evidence | Files Involved | Verification Strategy |
+|------|-----------|-----------|----------|----------------|----------------------|
+| 1 | {what might be wrong} | High/Med/Low | {code evidence supporting this} | {file paths} | {how to confirm or rule out} |
+| 2 | {alternative cause} | High/Med/Low | {evidence} | {files} | {verification} |
+
+### Code Smells in Affected Area
+| # | Smell | Location | Relevance to Bug |
+|---|-------|----------|-----------------|
+| 1 | {pattern — e.g., missing error handling, implicit type coercion} | {file:line} | {how it could cause or mask the bug} |
+
+### Dependency Analysis
+| Dependency | Version | Known Issues | Relevance |
+|-----------|---------|-------------|-----------|
+| {library/module} | {version} | {any known bugs or CVEs} | {how it relates to the symptoms} |
+
+### Recommended Investigation Order
+1. {hypothesis to test first — highest likelihood + easiest to verify}
+2. {next hypothesis}
+3. {etc.}
+
+### Ruling-Out Notes
+- {hypotheses already considered unlikely and why}
+```