@codyswann/lisa 1.67.3 → 1.69.0

package/plugins/lisa/commands/plan/create.md

@@ -3,4 +3,4 @@ description: "Creates an implementation plan from a ticket URL, file path, or te
 argument-hint: "<ticket-url | @file-path | description>"
 ---
 
-Use the /lisa:plan-execute skill on $ARGUMENTS
+Read `.claude/rules/intent-routing.md` and execute the **Plan** flow on $ARGUMENTS

package/plugins/lisa/commands/plan/execute.md

@@ -3,5 +3,4 @@ description: "Deploys an agent team to research, implement, review and deploy a
 argument-hint: "<ticket-url | @file-path | description>"
 ---
 
-
-Use the /lisa:plan-execute skill on $ARGUMENTS
+Read `.claude/rules/intent-routing.md` and determine the appropriate flow for $ARGUMENTS. Execute the full flow including implementation, review, and ship sub-flows.

package/plugins/lisa/commands/plan/improve-tests.md

@@ -0,0 +1,7 @@
+---
+description: "Improve test quality by analyzing and strengthening weak, brittle, or poorly-written tests"
+allowed-tools: ["Skill"]
+argument-hint: "<target-description>"
+---
+
+Use the /lisa:plan-improve-tests skill to improve test quality. $ARGUMENTS

package/plugins/lisa/commands/plan.md

@@ -0,0 +1,10 @@
+---
+description: "Plan work. Defines acceptance criteria, researches codebase, maps dependencies, and breaks down into ordered tasks."
+argument-hint: "<description-or-ticket-id-or-url>"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Plan** flow.
+
+If the argument is a JIRA ticket ID or URL, hand off to the `jira-agent` which will read the ticket and extract context.
+
+$ARGUMENTS

package/plugins/lisa/commands/review.md

@@ -0,0 +1,10 @@
+---
+description: "Review code changes. Runs quality, security, performance, product, and test reviews in parallel, then consolidates findings."
+argument-hint: "[pr-link-or-branch]"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Review** flow.
+
+Runs `quality-specialist`, `security-specialist`, and `performance-specialist` in parallel, followed by `product-specialist` and `test-specialist`. Consolidates all findings ranked by severity.
+
+$ARGUMENTS

package/plugins/lisa/commands/ship.md

@@ -0,0 +1,10 @@
+---
+description: "Ship current changes. Commits, opens PR, handles review feedback loop, deploys, verifies, and monitors."
+argument-hint: "[commit-message-hint]"
+---
+
+Read `.claude/rules/intent-routing.md` and execute the **Ship** flow.
+
+This includes: atomic commits, PR creation, review-fix loop (fix failed checks, resolve merge conflicts, handle bot review feedback until mergeable), merge, deploy, post-deploy verification, and monitoring.
+
+$ARGUMENTS

package/plugins/lisa/skills/acceptance-criteria/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: acceptance-criteria
+description: "Acceptance criteria definition. Gherkin user flows (Given/When/Then), error states, UX concerns, and empirical verification from the user perspective."
+---
+
+# Acceptance Criteria
+
+Evaluate changes from a non-technical user's perspective. Define acceptance criteria and verify behavior matches requirements.
+
+## Analysis Process
+
+1. **Understand the user goal** -- what problem does this solve for the end user?
+2. **Define user flows** -- step-by-step paths through the feature, including happy path and error paths
+3. **Write acceptance criteria** -- testable conditions from the user's perspective
+4. **Identify UX concerns** -- confusing interactions, missing feedback, accessibility issues
+5. **Map error states** -- what happens when things go wrong, and what the user sees
+6. **Run the feature** -- execute scripts, call APIs, or trigger the described behavior to verify empirically
+7. **Compare output to requirements** -- does actual behavior match expectations?
+
+## Output Format
+
+Structure findings as:
+
+```
+## Product Analysis
+
+### User Goal
+[1-2 sentence summary of what the user wants to accomplish]
+
+### User Flows (Gherkin)
+
+#### Happy Path
+Given [precondition]
+When [action]
+Then [expected outcome]
+
+#### Error Path: [description]
+Given [precondition]
+When [action that fails]
+Then [error handling behavior]
+
+### Acceptance Criteria
+- [ ] [criterion from user perspective]
+
+### UX Concerns
+- [concern] -- impact on user experience
+
+### Error Handling Requirements
+| Error Condition | User Sees | User Can Do |
+|----------------|-----------|-------------|
+
+### Verification Results
+For each acceptance criterion:
+- **Criterion:** [what was expected]
+- **Result:** Pass / Fail / Not Yet Testable
+- **Evidence:** [what was observed]
+
+### Out of Scope
+- [thing that might be expected but is not part of this work]
+```
+
+## Rules
+
+- Write acceptance criteria from the user's perspective, not the developer's
+- Every user flow must include at least one error path
+- Use Gherkin format (Given/When/Then) for user flows to enable direct translation into test cases
+- When verifying, always run the feature -- never review by only reading code
+- If you cannot run the feature (missing dependencies, services unavailable), report as a blocker -- do not guess
+- If the changes are purely internal (refactoring, config, tooling), report "No user-facing impact" and explain why
+- Do not propose UX changes beyond what was described -- flag scope concerns instead
+- Assume the reviewer has no technical background

package/plugins/lisa/skills/bug-triage/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: bug-triage
+description: "8-step bug triage and implementation workflow. Ensures bugs are reproducible, root-caused, and fixable before implementation begins."
+---
+
+# Bug Triage
+
+Follow this 8-step triage process before implementing any bug fix. Do not skip triage.
+
+## Triage Steps
+
+1. Verify you have all information needed to reproduce the bug (authentication requirements, environment information, etc.). Do not make assumptions. If anything is missing, stop and ask before proceeding.
+2. Reproduce the bug. If you cannot reproduce it, stop and report what you tried and what you observed.
+3. Once reproduced, verify you are 100% positive on how to fix it. If not, determine what you need to do to be 100% positive (e.g. add logging, trace the code path, inspect state) and do that first.
+4. Verify you have access to the tools, environments, and permissions needed to deploy and verify this fix (e.g. CI/CD pipelines, deployment targets, logging/monitoring systems, API access, database access). If any are missing or inaccessible, stop and raise them before starting implementation.
+5. Define the tests you will write to confirm the fix and prevent a regression.
+6. Define the documentation you will create or update to explain this bug so another developer understands the "how" and "what" behind it.
+7. If you can verify your fix before deploying to the target environment (e.g. start the app, invoke the API, open a browser, run the process, check logs), do so before deploying.
+8. Define how you will verify the fix beyond a shadow of a doubt (e.g. deploy to the target environment, invoke the API, open a browser, run the process, check logs).
+
+## Implementation
+
+Use the output of the triage steps above as your guide. Do not skip triage.

package/plugins/lisa/skills/codebase-research/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: codebase-research
+description: "Codebase exploration and architecture analysis. Read files, trace data flow, identify modification points, map dependencies, find reusable code, evaluate design patterns."
+---
+
+# Codebase Research
+
+Systematically explore and analyze a codebase to understand its architecture, trace data flow, and identify how to make changes safely.
+
+## Analysis Process
+
+Follow these steps in order. Do not skip steps or propose changes to code you have not read.
+
+### 1. Read Referenced Files
+
+- Read every file that is directly relevant to the task
+- Understand the current architecture before proposing changes
+- Read imports and dependencies to understand the module graph
+- Check for configuration files that affect behavior (tsconfig, eslint, webpack, etc.)
+
+### 2. Trace Data Flow
+
+- Follow the path from entry point to output for the affected feature
+- Identify every transformation the data undergoes
+- Map inputs, intermediate states, and outputs
+- Note where data crosses boundaries (API calls, database queries, message queues)
+
+### 3. Identify Modification Points
+
+- Determine which files, functions, and interfaces need changes
+- Note the exact lines where modifications are required
+- Identify any type definitions, schemas, or contracts that must be updated
+- Check for generated code that may need regeneration
+
+### 4. Map Dependencies
+
+- Identify what depends on the code being changed (downstream consumers)
+- Identify what the code being changed depends on (upstream providers)
+- Determine the safe modification order to avoid breaking intermediate states
+- Flag any circular dependencies
+
+### 5. Check for Reusable Code
+
+- Search for existing utilities, helpers, or patterns that apply to the task
+- Check shared libraries and common modules
+- Look for similar implementations elsewhere in the codebase that can be referenced
+- Prefer reusing existing code over creating new abstractions
+
+### 6. Evaluate Design Patterns
+
+- Match the codebase's existing patterns -- do not introduce new architectural patterns without reason
+- Check naming conventions, file organization, and code style
+- Identify any patterns that are partially implemented and should be completed
+- Note anti-patterns that should not be propagated
+
+## Output Format
+
+```text
+## Architecture Analysis
+
+### Files to Create
+- `path/to/file.ts` -- purpose
+
+### Files to Modify
+- `path/to/file.ts:L42-L68` -- what changes and why
+
+### Dependency Graph
+- [file A] -> [file B] -> [file C] (modification order)
+
+### Design Decisions
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+
+### Reusable Code
+- `path/to/util.ts:functionName` -- how it applies
+
+### Risks
+- [risk description] -- [mitigation]
+```
+
+## Rules
+
+- Always read files before recommending changes to them
+- Follow existing patterns in the codebase -- do not introduce new architectural patterns unless explicitly required
+- Include file:line references for all recommendations
+- Flag breaking changes explicitly
+- Keep the modification surface area as small as possible

package/plugins/lisa/skills/epic-triage/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: epic-triage
+description: "9-step epic triage and 5-step implementation workflow. Ensures epics are fully scoped, broken down, and ordered before execution begins."
+---
+
+# Epic Triage
+
+Follow this 9-step triage process before implementing any epic. Do not skip triage.
+
+## Triage Steps
+
+1. Verify you have all information needed to understand the full scope of this epic (goals, acceptance criteria, impacted systems, design specs, dependencies, etc.). Do not make assumptions. If anything is missing, stop and ask before proceeding.
+2. Verify the epic is broken down into concrete, well-scoped bugs, tasks, and/or stories that are each fully triaged. If ambiguities exist, stop and resolve them before breaking it down.
+3. Identify all cross-cutting concerns (auth, performance, security, data migrations, third-party integrations) that need to be addressed across the epic.
+4. Identify all dependencies between tasks within the epic, or on external epics, teams, or services. Determine the correct order of execution.
+5. Verify you have access to the tools, environments, and permissions needed to deploy and verify all tasks within this epic (e.g. CI/CD pipelines, deployment targets, logging/monitoring systems, API access, database access). If any are missing or inaccessible, stop and raise them before proceeding.
+6. Define the overall test strategy for the epic (unit, integration, end-to-end, load testing).
+7. Define the documentation that will need to be created or updated to cover the full scope of the epic so another developer understands the architecture, design decisions, and implementation.
+8. Define measurable acceptance criteria that confirm the epic is fully complete.
+9. Define how you will verify the epic is fully delivered beyond a shadow of a doubt (e.g. deploy to the target environment, walk through all acceptance criteria end-to-end, confirm all child tasks/stories are closed, confirm no regressions).
+
+## Implementation
+
+1. Use the output of the triage steps above as your guide. Do not skip triage.
+2. Work through each task and/or story in the order defined during triage, respecting dependencies.
+3. Apply the Bug Implementation and Task Implementation processes to each child bug or task, respectively, as you work through them.
+4. Continuously update the epic and its child issues in JIRA as progress is made.
+5. Do not consider the epic complete until all acceptance criteria are verified in the target environment and all child issues are resolved.

package/plugins/lisa/skills/nightly-add-test-coverage/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: nightly-add-test-coverage
+description: "Nightly direct-execution skill for increasing test coverage. Receives pre-computed threshold data, writes tests targeting coverage gaps, updates thresholds, commits, and creates a PR."
+allowed-tools: ["Edit", "MultiEdit", "Write", "Read", "Glob", "Grep", "Bash"]
+---
+
+# Nightly Test Coverage Improvement
+
+The caller provides pre-computed context:
+- **Package manager** (`npm`, `yarn`, or `bun`)
+- **Thresholds file** path (vitest.thresholds.json or jest.thresholds.json)
+- **Current thresholds** (statements, branches, functions, lines percentages)
+- **Proposed thresholds** (each metric increased by the coverage increment, capped at 90%)
+- **Metrics being bumped** (which metrics are below target)
+
+## Instructions
+
+1. Read CLAUDE.md and package.json for project conventions
+2. Run the project's coverage script with the provided package manager (e.g., `npm run test:cov`, `yarn test:cov`, or `bun run test:cov`) to get the coverage report -- identify gaps BEFORE reading any source files
+3. Parse the coverage output to identify the specific files and lines with the lowest coverage. Prioritize files with the most uncovered lines/branches.
+4. Read only the uncovered sections of source files using the coverage report line numbers -- do not explore the codebase broadly
+5. Write new tests to increase coverage enough to meet the proposed thresholds. Focus on the metrics being bumped -- write tests that cover untested branches, statements, functions, and lines.
+6. Re-run the coverage script with the provided package manager to verify the new thresholds pass
+7. Update the thresholds file with the proposed new threshold values
+8. Re-run the coverage script with the provided package manager to confirm the updated thresholds pass
+9. Commit all changes (new tests + updated thresholds file) with conventional commit messages
+10. Create a PR with `gh pr create` with a title like "test: increase test coverage: [metrics being bumped]" summarizing coverage improvements

package/plugins/lisa/skills/nightly-improve-tests/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: nightly-improve-tests
+description: "Nightly direct-execution skill for improving test quality. In nightly mode, focuses on tests for recently changed files. In general mode, scans all tests for the weakest ones. Commits and creates a PR."
+allowed-tools: ["Edit", "MultiEdit", "Write", "Read", "Glob", "Grep", "Bash"]
+---
+
+# Nightly Test Quality Improvement
+
+The caller provides:
+- **Mode**: "nightly" or "general"
+- **Changed files** (nightly mode only): list of source files changed in the last 24 hours
+
+## Nightly Mode
+
+1. Read CLAUDE.md and package.json for project conventions
+2. For each changed source file, find its corresponding test file(s)
+3. Analyze those test files for: missing edge cases, weak assertions (toBeTruthy instead of specific values), missing error path coverage, tests that test implementation rather than behavior
+4. Improve the test files with the most impactful changes
+5. Run the full test suite to verify all tests pass
+6. Commit changes with conventional commit messages
+7. Create a PR with `gh pr create` summarizing what was improved and why
+
+## General Mode
+
+1. Read CLAUDE.md and package.json for project conventions
+2. Scan the test files to find weak, brittle, or poorly-written tests
+3. Look for: missing edge cases, weak assertions (toBeTruthy instead of specific values), missing error path coverage, tests that test implementation rather than behavior
+4. Improve 3-5 test files with the most impactful changes
+5. Run the full test suite to verify all tests pass
+6. Commit changes with conventional commit messages
+7. Create a PR with `gh pr create` summarizing what was improved and why

package/plugins/lisa/skills/nightly-lower-code-complexity/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: nightly-lower-code-complexity
+description: "Nightly direct-execution skill for reducing code complexity thresholds. Receives pre-computed threshold data, refactors violations, updates thresholds, commits, and creates a PR."
+allowed-tools: ["Edit", "MultiEdit", "Write", "Read", "Glob", "Grep", "Bash"]
+---
+
+# Nightly Code Complexity Reduction
+
+The caller provides pre-computed context:
+- **Package manager** (`npm`, `yarn`, or `bun`)
+- **Current thresholds** (cognitiveComplexity, maxLinesPerFunction from eslint.thresholds.json)
+- **Proposed thresholds** (each metric decreased toward target minimums)
+- **Metrics being reduced** (which metrics are above target)
+
+## Instructions
+
+1. Read CLAUDE.md and package.json for project conventions
+2. Update eslint.thresholds.json with the proposed new threshold values (do NOT change the maxLines threshold)
+3. Run the project's lint script with the provided package manager (e.g., `npm run lint`, `yarn lint`, or `bun run lint`) to find functions that violate the new stricter thresholds
+4. For cognitive complexity violations: use early returns, extract helper functions, replace conditionals with lookup tables
+5. For max-lines-per-function violations: split large functions, extract helper functions, separate concerns
+6. Re-run the lint script with the provided package manager to verify all violations are resolved
+7. Run the project's test script with the provided package manager (e.g., `npm run test`, `yarn test`, or `bun run test`) to verify no tests are broken by the refactoring
+8. Commit all changes (refactored code + updated eslint.thresholds.json) with conventional commit messages
+9. Create a PR with `gh pr create` with a title like "refactor: reduce code complexity: [metrics being reduced]" summarizing the changes

package/plugins/lisa/skills/performance-review/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: performance-review
+description: "Performance review methodology. N+1 queries, inefficient algorithms, memory leaks, missing indexes, unnecessary re-renders, bundle size issues. Evidence-based recommendations."
+---
+
+# Performance Review
+
+Identify bottlenecks, inefficiencies, and scalability risks in code changes.
+
+## Analysis Process
+
+1. **Read affected files** -- understand data access patterns, algorithmic complexity, and resource usage
+2. **Identify N+1 queries** -- look for ORM calls inside loops, missing eager loading, unbatched database access
+3. **Check algorithmic complexity** -- nested loops over collections, repeated linear scans, unnecessary sorting
+4. **Evaluate memory usage** -- large object allocations, unbounded caches, retained references, memory leaks
+5. **Review database patterns** -- missing indexes, full table scans, unoptimized joins, excessive round trips
+6. **Check caching** -- missing cache layers, cache invalidation issues, redundant computations
+7. **Assess bundle/payload size** -- unnecessary imports, large dependencies, uncompressed responses
+8. **Review rendering performance** -- unnecessary re-renders, missing memoization, layout thrashing (frontend)
+
+## Output Format
+
+Structure findings as:
+
+```
+## Performance Analysis
+
+### Critical Issues
+Issues that will cause noticeable degradation at scale.
+
+- [issue] -- where in the code, why it matters, estimated impact
+
+### N+1 Query Detection
+| Location | Pattern | Fix |
+|----------|---------|-----|
+| file:line | Description of the N+1 | Eager load / batch / join |
+
+### Algorithmic Complexity
+| Location | Current | Suggested | Why |
+|----------|---------|-----------|-----|
+| file:line | O(n^2) | O(n) | Description |
+
+### Database Concerns
+- Missing indexes, unoptimized queries, excessive round trips
+
+### Memory Concerns
+- Unbounded growth, large allocations, retained references
+
+### Caching Opportunities
+- Computations or queries that could benefit from caching
+
+### Recommendations
+- [recommendation] -- priority (critical/warning/suggestion), estimated impact
+```
+
+## Common Patterns to Flag
+
+### N+1 Queries
+```typescript
+// Bad: N+1 -- one query per user inside loop
+const users = await userRepo.find();
+const profiles = await Promise.all(users.map(u => profileRepo.findOne({ userId: u.id })));
+
+// Good: Single query with join or batch
+const users = await userRepo.find({ relations: ["profile"] });
+```
+
+### Unnecessary Re-computation
+```typescript
+// Bad: Recomputes on every call
+const getExpensiveResult = () => heavyComputation(data);
+
+// Good: Compute once, reuse
+const expensiveResult = heavyComputation(data);
+```
+
+### Unbounded Collection Growth
+```typescript
+// Bad: Cache grows without limit
+const cache = new Map();
+const get = (key) => { if (!cache.has(key)) cache.set(key, compute(key)); return cache.get(key); };
+
+// Good: LRU or bounded cache
+const cache = new LRUCache({ max: 1000 });
+```
+
+## Rules
+
+- Focus on the specific changes proposed, not a full performance audit of the entire codebase
+- Flag only real performance risks -- do not micro-optimize code that runs once at startup
+- Quantify impact where possible (O(n) vs O(n^2), number of database round trips, estimated payload size)
+- Distinguish between critical issues (will degrade at scale) and suggestions (marginal improvement)
+- If the changes have no performance implications, report "No performance concerns" and explain why
+- Always consider the data scale -- an O(n^2) over 5 items is fine, over 10,000 is not

package/plugins/lisa/skills/plan-improve-tests/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: plan-improve-tests
+description: This skill should be used when improving test quality. It scans the test suite for weak, brittle, or poorly-written tests, generates a brief with improvement opportunities, and creates a plan with tasks to strengthen the tests.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+---
+
+# Improve Test Quality
+
+Target: $ARGUMENTS
+
+If no argument provided, scan the full test suite.
+
+## Step 1: Gather Requirements
+
+1. **Run test suite** to establish baseline:
+   ```bash
+   bun run test 2>&1 | tail -20
+   ```
+2. **Scan test files** for quality issues:
+   - Weak assertions (`toBeTruthy`, `toBeDefined` instead of specific values)
+   - Missing edge cases (no boundary values, no error paths)
+   - Implementation coupling (testing internals rather than behavior)
+   - Missing error path coverage
+   - Duplicated setup that could indicate missing abstractions
+3. **Identify 10-20 test files** with highest improvement potential, noting:
+   - File path
+   - Issues found (weak assertions, missing edge cases, etc.)
+   - Estimated impact of improvement
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```text
+Improve test quality across the test suite.
+
+Test files needing improvement (ordered by impact):
+1. [test file] - [issues found]
+   - Weak assertions: [count]
+   - Missing edge cases: [description]
+   - Implementation coupling: [description]
+2. ...
+
+Verification: `bun run test` -> Expected: All tests pass, improved assertions and coverage
+```
+
+Invoke `/plan-execute` with this brief to create the implementation plan.

package/plugins/lisa/skills/quality-review/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: quality-review
+description: "Code quality review checklist. Correctness, coding philosophy compliance, test coverage, documentation quality. Findings ranked by severity in plain English."
+---
+
+# Quality Review
+
+Review code quality for changed files. Explain all findings in plain English as if speaking to someone with no programming background.
+
+## Review Checklist
+
+For each changed file, evaluate:
+
+1. **Correctness** -- Does the code do what the task says? Logic errors, off-by-one mistakes, missing edge cases?
+2. **Coding philosophy** -- Immutability patterns (no `let`, no mutations, functional transformations)? Correct function structure (variables, side effects, return)?
+3. **Test coverage** -- Tests present? Testing behavior, not implementation details? Edge cases covered?
+4. **Documentation** -- JSDoc on new functions explaining "why"? Preambles on new files?
+5. **Code clarity** -- Readable variable names? Unnecessary complexity? Could a new team member understand this?
+
+## Output Format
+
+Rank findings by severity:
+
+### Critical (must fix before merge)
+Broken logic or violates hard project rules.
+
+### Warning (should fix)
+Could cause problems later or reduce maintainability.
+
+### Suggestion (nice to have)
+Minor improvements, not blocking.
+
+## Finding Format
+
+For each finding:
+
+- **What** -- Plain English description, no jargon
+- **Why** -- What could go wrong? Concrete examples
+- **Where** -- File path and line number
+- **Fix** -- Specific, actionable suggestion
+
+### Example
+
+> **What:** The function changes the original list instead of creating a new one.
+> **Why:** Other code using that list could see unexpected changes, causing hard-to-track bugs.
+> **Where:** `src/utils/transform.ts:42`
+> **Fix:** Use `[...items].sort()` instead of `items.sort()` to create a copy first.
+
+## Rules
+
+- Run `bun run test` to confirm tests pass
+- Run the task's proof command to confirm the implementation works
+- Never approve code with failing tests
+- If no issues found, say so clearly -- do not invent problems

package/plugins/lisa/skills/reproduce-bug/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: reproduce-bug
+description: "How to create reliable bug reproduction scenarios. Covers failing tests, minimal scripts, environment verification, and reproduction evidence capture."
+---
+
+# Reproduce Bug
+
+Before investigating root cause, reproduce the issue empirically. A bug that cannot be reproduced cannot be verified as fixed.
+
+## Reproduction Process
+
+### 1. Run the Failing Scenario
+
+- Execute the exact command, test, or request that triggers the bug
+- Capture the complete error output, stack trace, or unexpected behavior
+- Record the exact command used so it can be repeated
+
+### 2. Capture Evidence
+
+- Save the full error output (not just a summary)
+- Note the timestamp and environment details (OS, runtime version, dependency versions)
+- Screenshot or log any visual/UI issues
+- Record the actual behavior vs. the expected behavior
+
+### 3. Investigate Environment Differences (If Cannot Reproduce)
+
+If the issue does not reproduce locally:
+
+- Compare environment configurations (env vars, config files, feature flags)
+- Check runtime versions (Node.js, Python, Java, etc.)
+- Compare dependency versions (`package-lock.json`, `poetry.lock`, etc.)
+- Check data differences (database state, seed data, user roles)
+- Verify network conditions (DNS, proxies, firewalls, VPN)
+- Check for platform-specific behavior (OS, architecture, container vs. host)
+
+### 4. Create a Minimal Reproduction
+
+Create the smallest possible reproduction that triggers the bug:
+
+**Preferred: Failing test**
+- Write a test that exercises the exact code path and asserts the expected behavior
+- The test should fail with the same symptom as the reported bug
+- A failing test is the most reliable reproduction because it runs in CI and prevents regression
+
+**Fallback: Reproduction script**
+- Write a standalone script that triggers the issue
+- Minimize dependencies -- remove anything not needed to reproduce
+- Include setup steps (data seeding, config) in the script itself
+- The script should be runnable by anyone with access to the repo
+
+**Last resort: Manual steps**
+- Document exact click-by-click or command-by-command steps
+- Include prerequisite state (logged-in user, specific data, feature flags)
+- Note any timing-sensitive aspects (race conditions, timeouts)
+
+### 5. Verify Reproduction Is Reliable
+
+- Run the reproduction multiple times to confirm it consistently fails
+- For intermittent bugs, run enough iterations to establish the failure rate
+- If intermittent, note any patterns (timing, load, specific data)
+
+## Output Format
+
+```text
+## Reproduction
+
+### Command/Steps
+The exact command or steps to trigger the bug.
+
+### Actual Behavior
+What happens (error message, wrong output, crash).
+
+### Expected Behavior
+What should happen instead.
+
+### Environment
+- Runtime: [version]
+- OS: [platform]
+- Dependencies: [relevant versions]
+
+### Reproduction Type
+[ ] Failing test: [path to test file]
+[ ] Script: [path to script]
+[ ] Manual steps: [documented above]
+
+### Reliability
+[Always / Intermittent (N/M runs) / Conditional (only when X)]
+```
+
+## Rules
+
+- Never skip reproduction. If you cannot reproduce, report what you tried and what you observed.
+- A failing test is always the preferred reproduction method.
+- Capture complete error output -- do not truncate or summarize.
+- If the bug is environment-specific, document exactly which environment triggers it.
+- Do not begin root cause analysis until you have a reliable reproduction.