@gitwhy-cli/whyspec 0.1.17 → 0.1.19

package/skill-sources/whyspec-show/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: whyspec-show
+description: Use when reviewing the full story of a change — intent, design, tasks, and Decision Bridge delta.
+argument-hint: "[change-name]"
+---
+
+Show the full story — from intent through design, tasks, and reasoning — with the Decision Bridge delta.
+
+---
+
+**Input**: A change name. If omitted, prompt for available changes.
+
+## What Makes a Good Story
+
+The show command doesn't just dump files — it tells the **narrative arc** of a change:
+1. **Intent** — Why did we start this? What pain existed?
+2. **Design** — How did we plan to solve it? What trade-offs did we consider?
+3. **Tasks** — What concrete work was done? How much is complete?
+4. **Reasoning** — What actually happened? What surprised us?
+5. **Decision Bridge** — How did our thinking evolve from plan to reality?
+
+The Decision Bridge delta is the most valuable output — it reveals the gap between what we THOUGHT we'd do and what we ACTUALLY did.
+
+## Steps
+
+1. **Get the full story from CLI**
+
+   ```bash
+   whyspec show --json "<name>"
+   ```
+
+   Parse the JSON response:
+   - `intent`: Content of intent.md
+   - `design`: Content of design.md
+   - `tasks`: Content of tasks.md with completion status
+   - `context`: Content of ctx_<id>.md (if captured)
+   - `decision_bridge_delta`: Computed delta of planned vs actual decisions
+   - `surprises`: Decisions not in the original plan
+
+   If no change name provided:
+   - Run `whyspec list --json` to get available changes
+   - Let the user select
+
+2. **Display the full story as a narrative arc**
+
+   ```
+   # <Change Name>
+
+   ## Intent (WHY)
+   [From intent.md — problem statement, what it enables, constraints, success criteria]
+
+   ## Design (HOW)
+   [From design.md — approach, architecture, trade-offs considered]
+
+   ## Tasks (WHAT)
+   [From tasks.md — task list with completion status]
+   Progress: N/M tasks complete
+
+   ## Reasoning (AFTER)
+   [From ctx_<id>.md — story of what happened, decisions made, trade-offs accepted]
+   ```
+
+   If context hasn't been captured yet:
+   ```
+   ## Reasoning (AFTER)
+   Not yet captured. Run /whyspec:capture to complete the story.
+   ```
+
+3. **Highlight the Decision Bridge Delta**
+
+   When both plan files and context exist, display the evolution:
+
+   <examples>
+   <good>
+   ## Decision Bridge
+
+   | Decision | Planned (Before) | Actual (After) | Delta |
+   |----------|-------------------|----------------|-------|
+   | Rate limit storage | Redis vs in-memory? | Redis — 3 instances need shared state | As planned |
+   | Limit granularity | per-IP vs per-token? | Both — IP for anon, token for auth'd | Expanded scope |
+   | 429 response | standard vs custom? | Standard + Retry-After header | As planned |
+
+   ### Surprises (not in original plan)
+   - **Added X-Request-ID middleware** — needed for debugging 429 responses.
+     Impact: New dependency on uuid package, new middleware in chain.
+   - **Changed Redis key schema to sorted sets** — sliding window algorithm
+     requires sorted sets, not simple strings. Affects memory profile.
+
+   ### Delta Summary
+   - 3 planned decisions: 2 as planned, 1 expanded scope
+   - 2 surprises: both additive (no plan contradictions)
+   - Design alignment: HIGH — implementation closely followed the plan
+   Why good: Every decision shows BEFORE (question) and AFTER (answer + rationale).
+   Surprises are documented with impact. Delta summary gives the big picture.
+   The "Expanded scope" and "As planned" labels make evolution visible at a glance.
+   </good>
+
+   <bad>
+   ## Decision Bridge
+
+   | Decision | Status |
+   |----------|--------|
+   | Storage | Done |
+   | Limit scope | Done |
+   | 429 response | Done |
+   Why bad: No before/after comparison. "Done" tells you nothing about what
+   was decided or why. The entire point of the Decision Bridge is showing
+   how thinking evolved.
+   </bad>
+   </examples>
+
+4. **Handle partial stories gracefully**
+
+   Not every change has all files. Show what exists and guide the user:
+
+   | Missing | What to show | Suggestion |
+   |---------|-------------|------------|
+   | No design.md | Intent + Tasks only | "Design not captured. Was this a quick fix?" |
+   | No tasks.md | Intent + Design only | "No tasks defined. Run `/whyspec:execute` to start." |
+   | No context | Intent + Design + Tasks | "Reasoning not captured yet. Run `/whyspec:capture`." |
+   | No intent (shouldn't happen) | Whatever exists | "Intent missing — this change may not have been planned with WhySpec." |
+   | Tasks partially done | Show progress bar | "Progress: ███░░ 3/5 tasks — resume with `/whyspec:execute <name>`" |
+
+## Tools
+
+| Tool | When to use | When NOT to use |
+|------|------------|-----------------|
+| **Bash** | Run `whyspec show --json "<name>"` and `whyspec list --json` | Don't modify anything — this is read-only |
+| **Read** | Read raw files if CLI output is insufficient or truncated | Don't read files the CLI already provided |
+
+No AskUserQuestion — this is a read-only display skill. If change name is missing, use `whyspec list --json` and let the user select.
+
+## Guardrails
+
+- **Show all available phases** — always display intent, design, tasks, and context (if present). Don't skip sections.
+- **Always show the Decision Bridge delta** — when both plan and context exist, the delta table is mandatory.
+- **Handle missing files gracefully** — show what's available, note what's missing, suggest the command to fill gaps.
+- **Read-only** — this skill displays information. It never modifies files.
+- **Show completion status** — for tasks, show N/M complete. For the Decision Bridge, show resolved vs pending counts.
+- **Tell the story, don't dump data** — organize output as a narrative arc, not a raw file concatenation.

package/skills/whyspec-capture/SKILL.md

@@ -1,154 +0,0 @@
----
-name: whyspec-capture
-description: Capture reasoning after implementation — resolve the Decision Bridge by mapping planned decisions to actual outcomes and recording surprises. Use after coding to preserve the WHY behind what was built.
----
-
-Capture reasoning — create a context file that resolves the Decision Bridge and preserves the full story.
-
-View the complete story with `/whyspec-show`
-
----
-
-**Input**: Optionally specify a change name. If omitted, auto-detect the most recently executed change.
-
-**Steps**
-
-1. **Select the change**
-
-   If a name is provided, use it. Otherwise:
-   - Auto-detect the most recently executed change (look for changes with completed tasks)
-   - If ambiguous, run `whyspec list --json` and use **AskUserQuestion** to select
-
-2. **Read plan files for Decision Bridge mapping**
-
-   Read these files from the change folder — **required** before generating context:
-   - `<path>/intent.md` — the stated intent, "Decisions to Make" checkboxes
-   - `<path>/design.md` — the approach, "Questions to Resolve" items
-
-   Extract and track:
-   - Every `- [ ]` or `- [x]` item under "Decisions to Make" → each MUST be resolved in the context
-   - Every item under "Questions to Resolve" → each MUST be answered
-   - The stated constraints and success criteria → compare against what actually happened
-
-3. **Get capture data from CLI**
-
-   ```bash
-   whyspec capture --json "<name>"
-   ```
-
-   Parse the JSON response:
-   - `template`: Context file template
-   - `commits`: Commits associated with this change (auto-detected from git)
-   - `files_changed`: Files modified during implementation (auto-detected)
-   - `decisions_to_make`: Decision checkboxes extracted from plan files
-   - `change_name`: The change name for the header
-
-4. **Populate the Decision Bridge**
-
-   This is the core of the capture. Map every planned decision to its outcome:
-
-   a. **Decisions to Make → Decisions Made**: For EACH checkbox from intent.md's "Decisions to Make", record:
-      - What was decided
-      - Why (the rationale — not just the choice, but the reasoning)
-      - Any constraints that influenced the decision
-
-   b. **Questions to Resolve → Answers**: For EACH question from design.md's "Questions to Resolve", record:
-      - The answer that emerged during implementation
-      - How it was determined
-
-   c. **Capture Surprises**: Identify decisions made during implementation that were NOT in the original plan. Ask yourself:
-      - "What did we decide that we didn't plan to decide?"
-      - "What changed from the original design?"
-      - "What unexpected requirements emerged?"
-      These surprises are often the most valuable part of the context.
-
-   If a planned decision was NOT made during implementation, note it as unresolved and ask the user.
-
-5. **Generate ctx_<id>.md in SaaS XML format**
-
-   Write to `<path>/ctx_<id>.md` using the GitWhy SaaS format:
-
-   ```xml
-   <context>
-     <title>Short title describing what was built and why</title>
-
-     <story>
-       Phase-organized engineering journal. First-person, chronological.
-       Capture the FULL reasoning — not a summary.
-
-       Phase 1 — [Setup/Context]:
-       What the user asked for, initial understanding, preparation work.
-
-       Phase 2 — [Implementation]:
-       What was built, key decision points encountered, problems solved.
-       Reference specific files and approaches.
-
-       Phase 3 — [Verification]:
-       How the work was verified, test results, manual checks.
-     </story>
-
-     <reasoning>
-       Why this approach was chosen over alternatives.
-
-       <decisions>
-         - [Planned decision] — [chosen option] — [rationale]
-         - [Planned decision] — [chosen option] — [rationale]
-       </decisions>
-
-       <rejected>
-         - [Alternative not chosen] — [why it was rejected]
-       </rejected>
-
-       <tradeoffs>
-         - [Trade-off accepted] — [what was gained vs lost]
-       </tradeoffs>
-     </reasoning>
-
-     <files>
-       path/to/file.ts — new — Brief description
-       path/to/other.ts — modified — Brief description
-     </files>
-
-     <agent>claude-code (model-name)</agent>
-     <tags>comma, separated, domain, keywords</tags>
-     <verification>Test results and build status</verification>
-     <risks>Open questions, follow-up items, known limitations</risks>
-   </context>
-   ```
-
-   **Surprises** go in the `<story>` narrative AND as a clearly labeled section in `<reasoning>`:
-
-   ```
-   Surprises (decisions not in the original plan):
-   - [Unexpected decision] — [why it was needed]
-   - [Scope change] — [what triggered it]
-   ```
-
-6. **Show summary**
-
-   ```
-   ## Reasoning Captured: <name>
-
-   Context: ctx_<id>.md
-
-   Decision Bridge:
-     Planned decisions resolved: N/N
-     Questions answered: N/N
-     Surprises captured: N
-
-   Files documented: N
-   Commits linked: N
-
-   View the full story: /whyspec-show <name>
-   ```
-
-**Guardrails**
-
-- **Must read plan files FIRST** — never generate context without reading intent.md and design.md. The Decision Bridge requires mapping FROM plan TO outcome.
-- **Every planned decision must be resolved** — if intent.md lists 5 "Decisions to Make", all 5 must appear in the context. Prompt the user for any that weren't addressed.
-- **Never skip surprises** — unplanned decisions are the most valuable context. Actively search for them.
-- **Capture reasoning, not summaries** — write "we chose X because Y outweighs Z in our constraints" not just "we used X." Full reasoning helps future developers understand the choice.
-- **Use SaaS XML format exactly** — the `<context>` tags must match the GitWhy format so `git why log` and `git why push` work without conversion.
-- **Include verification results** — what tests pass, what was manually verified. This grounds the context in evidence.
-- **Don't fabricate rationale** — if you don't know why a decision was made, ask the user. Invented reasoning is worse than no reasoning.
-- **One context per capture** — each `/whyspec-capture` invocation creates exactly one `ctx_<id>.md` file.

package/skills/whyspec-debug/SKILL.md

@@ -1,404 +0,0 @@
----
-name: whyspec-debug
-description: Debug with scientific method — gather symptoms, form falsifiable hypotheses, test systematically, verify root cause before fixing. Searches team knowledge first and captures the full investigation as persistent context.
----
-
-# WhySpec Debug — Scientific Investigation
-
-Debug systematically. No fix without root cause.
-
-This skill implements a structured debugging process that captures the full investigation
-as persistent context — symptoms, hypotheses, evidence, root cause, and fix rationale.
-
-The investigation is automatically saved as a context file when resolved.
-
----
-
-## Purpose
-
-Debugging is not guessing. This skill enforces:
-
-1. **Team knowledge first** — search past reasoning before reinventing
-2. **Scientific method** — falsifiable hypotheses tested with evidence
-3. **Iron Law** — no fix is proposed until root cause is verified
-4. **Persistent state** — debug.md survives context resets so investigations can resume
-5. **Reasoning capture** — every investigation produces a context file for future developers
-
----
-
-**Input**: A bug description, error message, or change name for an existing debug session.
-
----
-
-## Step 0: Team Knowledge Search
-
-Before investigating, check if someone has reasoned about this domain before:
-
-```bash
-whyspec search --json "<keywords from bug description>"
-```
-
-If results exist:
-- Display: "Found N past contexts in this domain"
-- List relevant titles and key decisions from past investigations
-- Note any past decisions that might inform the current bug
-
-If no results: note "No prior context found" and continue.
-
-This step takes seconds. It prevents re-investigating solved problems and surfaces past decisions that may explain the current behavior.
-
----
-
-## Step 1: Symptoms Gathering
-
-Create the debug session:
-
-```bash
-whyspec debug --json "<bug-name>"
-```
-
-Parse the JSON response:
-- `path`: Debug session directory (e.g., `.gitwhy/changes/<bug-name>/`)
-- `template`: debug.md template structure
-- `related_contexts`: Past contexts in the same domain (from Step 0)
-
-**Gather symptoms** — use **AskUserQuestion** if the user hasn't provided enough detail, or investigate the codebase directly:
-
-| Symptom | What to capture |
-|---------|----------------|
-| Expected behavior | What SHOULD happen |
-| Actual behavior | What ACTUALLY happens |
-| Error messages | Exact text, stack traces, error codes |
-| Reproduction steps | Minimal sequence to trigger the bug |
-| Timeline | When it started, what changed recently |
-| Scope | Who is affected, how often, which environments |
-
-**Write debug.md immediately** — this file IS the investigation state:
-
-```markdown
-# Debug: <bug-name>
-
-## Status: INVESTIGATING
-
-## Symptoms
-
-**Expected:** [what should happen]
-**Actual:** [what actually happens]
-**Error:**
-```
-[exact error message or stack trace]
-```
-**Reproduction:** [minimal steps to reproduce]
-**Timeline:** [when it started, what changed recently]
-**Scope:** [who/what is affected, frequency]
-
-## Related Past Contexts
-
-[Results from Step 0, or "None found"]
-[If found: relevant decisions, reasoning excerpts]
-
-## Hypotheses
-
-[Populated in Step 2]
-
-## Evidence Log
-
-[Populated in Step 3]
-
-## Root Cause
-
-[Populated in Step 4]
-
-## Fix
-
-[Populated in Step 5]
-
-## Prevention
-
-[Populated in Step 5]
-```
-
-**CRITICAL**: Write debug.md to `<path>/debug.md` NOW, after this step. It persists across context resets and enables resuming the investigation.
-
----
-
-## Step 2: Hypothesis Formation
-
-Form **3 or more falsifiable hypotheses**. Each must include a specific claim, a concrete test, and a way to disprove it:
-
-```markdown
-## Hypotheses
-
-### H1: [Specific, testable claim about the root cause]
-- **Test:** [Concrete action — a command to run, a log to check, a condition to verify]
-- **Disproof:** [What evidence would prove this hypothesis WRONG]
-- **Status:** UNTESTED
-- **Likelihood:** HIGH / MEDIUM / LOW
-
-### H2: [Different claim — consider a different subsystem or mechanism]
-- **Test:** [Concrete action]
-- **Disproof:** [What would disprove it]
-- **Status:** UNTESTED
-- **Likelihood:** HIGH / MEDIUM / LOW
-
-### H3: [Third claim — consider edge cases, race conditions, configuration]
-- **Test:** [Concrete action]
-- **Disproof:** [What would disprove it]
-- **Status:** UNTESTED
-- **Likelihood:** HIGH / MEDIUM / LOW
-```
-
-**Hypothesis quality rules:**
-- Each hypothesis must be **specific enough to test** — "something is wrong with auth" is not a hypothesis
-- Each hypothesis must be **falsifiable** — there must be evidence that could prove it wrong
-- Hypotheses should target **different root causes** — not three variations of the same idea
-- **Use past contexts**: if Step 0 found related reasoning, let those decisions inform your hypotheses. A past choice ("we used X because of Y") might explain the current behavior.
-
-Rank by likelihood. Test the most likely first.
-
-Update debug.md with all hypotheses before proceeding.
-
----
-
-## Step 3: Hypothesis Testing
-
-Test each hypothesis **one at a time, sequentially**. For each:
-
-1. **Execute the test** described in the hypothesis
-2. **Record evidence** — exact output, logs, observed behavior
-3. **Evaluate** — does the evidence support, refute, or leave the hypothesis inconclusive?
-4. **Update status**: `CONFIRMED`, `DISPROVED`, or `INCONCLUSIVE`
-5. **Update debug.md immediately** with findings
-
-```markdown
-## Evidence Log
-
-### H1: [claim] — DISPROVED
-**Test performed:** [exact command or action taken]
-**Evidence:**
-```
-[exact output, log entries, or observations]
-```
-**Conclusion:** [why this hypothesis is disproved — what the evidence shows]
-
-### H2: [claim] — CONFIRMED
-**Test performed:** [exact command or action taken]
-**Evidence:**
-```
-[exact output showing the root cause]
-```
-**Conclusion:** [why this is confirmed — the causal link between evidence and symptom]
-```
-
-**Testing rules:**
-
-- **One hypothesis at a time** — never test multiple simultaneously. Confounded evidence is useless.
-- **Max 3 tests per hypothesis** — if evidence is inconclusive after 3 attempts, mark INCONCLUSIVE and move to the next.
-- **Preserve the crime scene** — before modifying suspect code, record its current state in the evidence log.
-- **Update debug.md after each test** — don't batch. Each test result is written immediately.
-
-If ALL hypotheses are disproved or inconclusive:
-- Form new hypotheses based on what the evidence revealed
-- If still stuck after a second round, escalate to the user (see Escalation Rules)
-
----
-
-## Step 4: Root Cause Verification — The Iron Law
-
-**No fix without verified root cause.**
-
-Before proposing ANY fix, you must:
-
-1. **State the root cause clearly and specifically**
-2. **Explain the causal chain**: [trigger] → [mechanism] → [symptom]
-3. **Verify predictive power**: can you predict the symptom from the cause? Can you reliably reproduce it?
-
-Update debug.md:
-
-```markdown
-## Root Cause
-
-**Cause:** [precise description of what is wrong — not symptoms, the actual defect]
-**Causal chain:** [trigger event] → [mechanism/code path] → [observed symptom]
-**Verified by:** [how the causal link was confirmed — which test, which evidence]
-**Confidence:** HIGH / MEDIUM / LOW
-```
-
-**Confidence thresholds:**
-
-| Confidence | Criteria | Action |
-|-----------|----------|--------|
-| HIGH | Reproduction is reliable, causal chain is clear, evidence is unambiguous | Proceed to fix |
-| MEDIUM | Strong evidence but some uncertainty remains | Proceed with caution, note risks |
-| LOW | Circumstantial evidence, cannot reliably reproduce | **Escalate to user** — do NOT fix |
-
-If confidence is LOW:
-- Present all evidence gathered to the user via **AskUserQuestion**
-- Show: what was tested, what was found, what remains uncertain
-- Ask for additional context, access, or direction
-- **Do NOT guess at a fix**
-
-Update debug.md status: `## Status: ROOT CAUSE IDENTIFIED`
-
----
-
-## Step 5: Fix + Auto-Capture
-
-Once root cause is verified with HIGH or MEDIUM confidence:
-
-### 5a. Implement the fix
-
-- Make the **minimal, targeted change** that addresses the root cause
-- Don't refactor surrounding code — fix the bug, nothing more
-- Verify the fix resolves the symptom (run the reproduction steps again)
-
-### 5b. Update debug.md
-
-```markdown
-## Fix
-
-**Change:** [what was modified and how]
-**Files:** [files changed]
-**Verification:** [how the fix was confirmed — test results, manual reproduction]
-
-## Prevention
-
-**How to prevent recurrence:**
-- [Concrete preventive measure — e.g., "add input validation for X"]
-- [Process improvement — e.g., "add test case for this edge case"]
-- [Monitoring — e.g., "add alert for this error pattern"]
-```
-
-Update debug.md status: `## Status: RESOLVED`
-
-### 5c. Commit the fix
-
-Commit atomically with a clear message referencing the root cause.
-
-### 5d. Auto-capture reasoning
-
-Generate a context file to preserve the full investigation:
-
-```bash
-whyspec capture --json "<bug-name>"
-```
-
-Write `<path>/ctx_<id>.md` in SaaS XML format:
-
-```xml
-<context>
-  <title>Debug: [short description — bug and fix]</title>
-
-  <story>
-    Phase 1 — Symptoms:
-    [What was observed, when it started, reproduction steps]
-
-    Phase 2 — Investigation:
-    [Hypotheses formed, tests performed, evidence gathered]
-    [Which hypotheses were disproved and why]
-
-    Phase 3 — Root Cause:
-    [The actual defect, causal chain, how it was verified]
-
-    Phase 4 — Fix:
-    [What was changed, how the fix was confirmed]
-  </story>
-
-  <reasoning>
-    Why the bug existed and why this fix is correct.
-
-    <decisions>
-      - [Fix approach chosen] — [rationale for this approach]
-    </decisions>
-
-    <rejected>
-      - [Alternative fix considered] — [why it was rejected]
-      - [Disproved hypothesis] — [what evidence ruled it out]
-    </rejected>
-
-    <tradeoffs>
-      - [Any trade-offs in the fix — scope, performance, complexity]
-    </tradeoffs>
-  </reasoning>
-
-  <files>
-    [Files changed to fix the bug]
-  </files>
-
-  <verification>[Test results confirming the fix]</verification>
-  <risks>[Potential side effects, related areas to watch]</risks>
-</context>
-```
-
-### 5e. Show summary
-
-```
-## Debug Complete: <bug-name>
-
-Root cause: [one-line summary]
-Fix: [what was changed]
-Context: ctx_<id>.md
-
-Investigation:
-  Hypotheses tested: N (M confirmed, P disproved)
-  Evidence entries: N
-  Past contexts referenced: N
-
-View full investigation: /whyspec-show <bug-name>
-```
-
----
-
-## Resuming an Investigation
-
-If the user invokes `/whyspec-debug` and a `debug.md` already exists for that change:
-
-1. **Read debug.md** from the change folder
-2. **Check the Status field** and resume from the appropriate step:
-
-| Status | Resume from |
-|--------|-------------|
-| `INVESTIGATING` | Last completed step — check which sections are populated |
-| `ROOT CAUSE IDENTIFIED` | Step 5 — implement the fix |
-| `RESOLVED` | Investigation is complete — show summary |
-
-3. **Announce**: "Resuming debug session: <name> — Status: <status>"
-4. **Show progress**: display completed sections and what remains
-
-This is why writing debug.md incrementally is critical — it's the contract for resumability.
-
----
-
-## Escalation Rules
-
-Escalate to the user (via **AskUserQuestion**) when:
-
-| Trigger | What to present |
-|---------|----------------|
-| All hypotheses disproved (2 rounds) | Full evidence summary, ask for new direction |
-| Cannot reproduce | Symptoms documented, ask for environment details or access |
-| Root cause outside codebase | Findings documented, suggest infrastructure/environment investigation |
-| Root cause confidence is LOW | Evidence summary, explain uncertainty, ask for guidance |
-| Fix would introduce significant risk | Proposed fix, risk assessment, ask for approval |
-
-When escalating, always present:
-- What was tested and what was found
-- What remains uncertain
-- A specific question or request for the user
-
-**Never silently give up.** If you're stuck, say so with evidence.
-
----
-
-## Guardrails
-
-- **No fix without root cause** — the Iron Law is non-negotiable. Never propose a fix based on a guess, a hunch, or pattern-matching without evidence.
-- **Max 3 tests per hypothesis** — if evidence is inconclusive after 3 attempts, mark INCONCLUSIVE and form new hypotheses or escalate.
-- **Always capture reasoning** — every debug session MUST produce both `debug.md` AND `ctx_<id>.md`. No silent fixes. The investigation is as valuable as the fix.
-- **Write debug.md incrementally** — update after EVERY step, not at the end. This is the resumability contract. If context resets, the investigation survives.
-- **Don't skip team knowledge** — always run Step 0, even for "obvious" bugs. Past contexts prevent repeated mistakes and surface relevant decisions.
-- **Don't guess at root cause** — if uncertain after investigation, escalate. Wrong diagnosis leads to wrong fixes that mask the real problem.
-- **Test one hypothesis at a time** — never test multiple simultaneously. Sequential testing produces clean evidence.
-- **Preserve evidence** — before modifying suspect code, record its current state. Don't destroy the crime scene.
-- **Minimal fixes only** — fix the bug, don't refactor. Keep the diff focused on the root cause.
-- **Don't skip prevention** — after fixing, always document how to prevent recurrence. Future developers need this.