@brunosps00/dev-workflow 0.8.1 → 0.10.0

package/scaffold/skills/dw-codebase-intel/references/intel-format.md

@@ -0,0 +1,208 @@
+# Intel format — schemas of `.dw/intel/` files
+
+Every command that reads `.dw/intel/` depends on these schemas. Treat this file as the contract.
+
+## Layout
+
+```
+.dw/intel/
+├── stack.json           # languages, frameworks, build/test tooling
+├── files.json           # per-file imports/exports/type
+├── apis.json            # routes, endpoints, CLI commands
+├── deps.json            # third-party dependencies + usage
+├── arch.md              # architectural overview (markdown)
+└── .last-refresh.json   # change detection (timestamps + sha256 hashes)
+```
+
+## Common `_meta` block (all JSON files)
+
+```json
+{
+  "_meta": {
+    "updated_at": "2026-05-06T12:34:56.789Z",
+    "version": 3
+  }
+}
+```
+
+- `updated_at`: ISO-8601 UTC timestamp, set on every write
+- `version`: integer, starts at 1, increments on every update (full or partial)
+
+## `stack.json`
+
+```json
+{
+  "_meta": { "updated_at": "...", "version": 1 },
+  "languages": ["TypeScript", "JavaScript"],
+  "frameworks": ["Express", "React"],
+  "tools": ["ESLint", "Jest", "Docker"],
+  "build_system": "npm scripts",
+  "test_framework": "Jest",
+  "package_manager": "npm",
+  "content_formats": ["Markdown", "YAML", "EJS"]
+}
+```
+
+Field rules:
+- `languages`: ordered by line count (most-prevalent first)
+- `frameworks`: full names (no abbreviations) — `"Next.js"` not `"next"`
+- `tools`: dev tooling that affects code shape (linter, formatter, bundler, container runtime)
+- `build_system`: detected from manifest (`npm scripts`, `Vite`, `webpack`, `esbuild`, `dotnet`, `cargo`, etc.)
+- `test_framework`: detected from manifest (`Jest`, `Vitest`, `Pytest`, `xUnit`, `cargo test`, etc.); `"none"` if no test setup detected
+- `package_manager`: from lockfile (`npm`, `pnpm`, `yarn`, `poetry`, `uv`, `dotnet`, `cargo`)
+- `content_formats`: non-code formats with structural significance (markdown for docs/skills, YAML for configs, JSON Schema, OpenAPI, Protobuf, etc.)
+
+## `files.json`
+
+```json
+{
+  "_meta": { "updated_at": "...", "version": 1 },
+  "entries": {
+    "src/server.ts": {
+      "exports": ["createServer", "default"],
+      "imports": ["./config", "express", "./routes/users"],
+      "type": "entry-point"
+    },
+    "src/routes/users.ts": {
+      "exports": ["userRouter"],
+      "imports": ["express", "../db", "../schemas/user"],
+      "type": "module"
+    }
+  }
+}
+```
+
+Field rules:
+- Key: file path relative to project root, forward slashes
+- `exports`: array of ACTUAL exported symbol names. NOT descriptions. `["createServer", "default"]` is correct; `["server creation"]` is wrong.
+- `imports`: array of import specifiers (relative paths or package names) — preserve as the source code writes them
+- `type`: one of `entry-point`, `module`, `config`, `test`, `script`, `type-def`, `style`, `template`, `data`
+
+Coverage: target the most important 50-100 files. Skip generated code, test files (unless they reveal architecture), `node_modules/dist/build`.
+
+## `apis.json`
+
+```json
+{
+  "_meta": { "updated_at": "...", "version": 1 },
+  "entries": {
+    "GET /api/users": {
+      "method": "GET",
+      "path": "/api/users",
+      "params": ["page", "limit"],
+      "file": "src/routes/users.ts",
+      "description": "List users with pagination"
+    },
+    "CLI: dw-init": {
+      "method": "CLI",
+      "path": "dev-workflow init",
+      "params": ["--lang", "--force"],
+      "file": "bin/dev-workflow.js",
+      "description": "Scaffold .dw/ structure into a project"
+    }
+  }
+}
+```
+
+Field rules:
+- Key format: `"<METHOD> <PATH>"` for HTTP, `"CLI: <command>"` for CLI, `"GraphQL: <operation>"`, `"Handler: <event>"`, etc.
+- `method`: HTTP verb, or `"CLI"`, `"GraphQL"`, `"gRPC"`, `"Event"`, `"Subscription"`
+- `path`: the route/command/operation name
+- `params`: query/body/CLI flag names — array of strings
+- `file`: source path
+- `description`: one-line summary derived from the handler's first comment or function name
+
+If no API surfaces detected, write `{ "_meta": {...}, "entries": {} }` — never omit the file.
+
+## `deps.json`
+
+```json
+{
+  "_meta": { "updated_at": "...", "version": 1 },
+  "entries": {
+    "express": {
+      "version": "^4.18.0",
+      "type": "production",
+      "used_by": ["src/server.ts", "src/routes/users.ts"],
+      "invocation": "require"
+    },
+    "vitest": {
+      "version": "^2.0.0",
+      "type": "development",
+      "used_by": ["package.json#test"],
+      "invocation": "npm test"
+    }
+  }
+}
+```
+
+Field rules:
+- Key: package name (npm), distribution name (PyPI), package id (NuGet), crate name (crates.io)
+- `version`: semver range from manifest
+- `type`: `production` | `development` | `peer` | `optional`
+- `used_by`: array of file paths that import the dep (verified by Grep) OR npm-script keys for tooling deps
+- `invocation`:
+  - `require` if directly imported in code
+  - npm script command (`npm run lint`, `npm test`) if exercised via script
+  - `implicit` if a runtime/framework dep that's not directly imported (e.g., `react-dom` in a Next.js project)
+
+## `arch.md`
+
+```markdown
+---
+updated_at: "2026-05-06T12:34:56.789Z"
+---
+
+## Architecture Overview
+
+The project follows a layered architecture: HTTP routes → application services → repository layer → ORM → database.
+
+## Key Components
+
+| Component | Path | Responsibility |
+|-----------|------|----------------|
+| Server bootstrap | `src/server.ts` | Express app initialization + middleware wiring |
+| Route handlers | `src/routes/` | HTTP request validation and response shaping |
+| Application services | `src/services/` | Business logic, orchestration |
+| Repositories | `src/repositories/` | Data access via Prisma |
+| Schemas | `src/schemas/` | Zod validation schemas, shared with frontend |
+
+## Data Flow
+
+`HTTP request` → `route handler (validates with Zod)` → `service` → `repository (Prisma)` → `Postgres` → response
+
+## Conventions
+
+- File naming: kebab-case (`user-routes.ts`, `order-service.ts`)
+- Function naming: camelCase, verb-first (`createOrder`, `findUserById`)
+- Tests: co-located, `.test.ts` suffix
+- Imports: absolute via `@/` alias for cross-module, relative for sibling files
+```
+
+## `.last-refresh.json`
+
+```json
+{
+  "updated_at": "2026-05-06T12:34:56.789Z",
+  "files": {
+    "stack.json": "a3c8b1...",
+    "files.json": "f9e2d7...",
+    "apis.json": "1b4f8a...",
+    "deps.json": "5c2e6b...",
+    "arch.md": "9d7c3e..."
+  }
+}
+```
+
+Hashes are SHA-256 of file contents at the moment of refresh. Used by `/dw-map-codebase` to detect drift on the next run and decide whether a partial update is enough.
+
+## Validation rules
+
+When `intel-updater` finishes, all 5 files MUST satisfy:
+
+1. Valid JSON (parseable)
+2. `_meta.updated_at` is ISO-8601
+3. `_meta.version` is a positive integer
+4. All file paths in `files.json`, `apis.json`, `deps.json` exist on disk (or were excluded for known reasons)
+5. `exports` arrays contain only actual symbols (no descriptions, no spaces in entries)
+6. No secrets/credentials/tokens in any file

package/scaffold/skills/dw-codebase-intel/references/query-patterns.md

@@ -0,0 +1,148 @@
+# Query patterns — how `/dw-intel` answers different question shapes
+
+`/dw-intel "<query>"` reads `.dw/intel/` and returns structured answers with file paths cited. This file describes how the command maps natural-language queries to which intel files to read.
+
+## Query shape detection
+
+The command classifies the query into one of these shapes before searching:
+
+| Shape | Example queries | Primary file | Secondary files |
+|-------|-----------------|--------------|-----------------|
+| **where-is** | "where is the user routes file?", "where is auth defined?" | `files.json` | `apis.json` |
+| **what-uses** | "what uses express?", "where is the redis client called?" | `deps.json` (for libs), `files.json` (for symbols) | grep fallback |
+| **architecture-of** | "what's the architecture?", "how is data flow structured?" | `arch.md` | `stack.json` |
+| **stack** | "what frameworks?", "is this typescript or javascript?" | `stack.json` | — |
+| **dep-info** | "which version of react?", "what's prisma used for here?" | `deps.json` | — |
+| **api-list** | "list endpoints", "what routes exist?" | `apis.json` | — |
+| **find-export** | "where is `createServer` exported from?", "find the `userSchema` symbol" | `files.json` (search `exports` arrays) | grep fallback |
+| **convention** | "what's the file naming convention?", "are tests co-located?" | `arch.md` | `.dw/rules/` if available |
+
+## Match algorithm
+
+For each shape, the command:
+
+1. **Tokenize** the query into keywords (drop stopwords).
+2. **Search the primary file** for matches:
+   - JSON files: case-insensitive substring match in keys + descriptions
+   - `arch.md`: case-insensitive full-text search
+3. **Rank** matches by:
+   - Exact symbol match > substring match > description match
+   - Direct deps > indirect (transitive) deps
+4. **Return** top 3-5 matches with file paths cited.
+
+If primary file yields zero matches, fall back to secondary files. If still zero, fall back to direct grep over the project (slower but exhaustive).
+
+## Examples
+
+### Query: "where is auth defined?"
+
+**Shape:** where-is
+
+**Process:**
+1. Search `files.json` for keys containing `auth` → finds `src/auth/index.ts`, `src/middleware/auth.ts`, `src/routes/auth.ts`
+2. Search `apis.json` for paths containing `auth` → finds `POST /api/auth/login`, `POST /api/auth/logout`
+3. Return top files + endpoints with paths
+
+**Output:**
+```
+Auth is defined across 3 files and exposes 2 endpoints:
+
+Files:
+- src/auth/index.ts        (entry-point) — exports: configureAuth, AuthError
+- src/middleware/auth.ts   (module)      — exports: requireAuth, optionalAuth
+- src/routes/auth.ts       (module)      — exports: authRouter
+
+Endpoints:
+- POST /api/auth/login   (file: src/routes/auth.ts) — Authenticate user
+- POST /api/auth/logout  (file: src/routes/auth.ts) — Clear session
+```
+
+### Query: "what uses redis?"
+
+**Shape:** what-uses
+
+**Process:**
+1. Search `deps.json` for entry `redis` (or `ioredis`, `redis-py`, etc. depending on stack)
+2. Read its `used_by` array
+3. Cross-reference with `files.json` to enrich (which files have this dep imported and what they do)
+
+**Output:**
+```
+Redis (ioredis@^5.3.0, production) is used by 3 files:
+
+- src/cache/index.ts        — exports: cacheGet, cacheSet, cacheDel
+- src/jobs/queue.ts         — exports: enqueueJob (uses ioredis as BullMQ backend)
+- src/sessions/store.ts     — exports: createSessionStore
+```
+
+### Query: "what frameworks?"
+
+**Shape:** stack
+
+**Process:**
+1. Read `stack.json` directly
+2. Output the `frameworks` field, with versions if available from `deps.json`
+
+**Output:**
+```
+Frameworks detected:
+- Express (^4.18.0, production)
+- React (^18.2.0, production)
+- Prisma (^5.4.0, production)
+
+Build system: npm scripts
+Test framework: Jest
+Package manager: npm
+```
+
+### Query: "list endpoints"
+
+**Shape:** api-list
+
+**Process:**
+1. Read `apis.json`
+2. Group by tag/prefix (`/api/users`, `/api/orders`, `/api/auth` → User Management, Orders, Auth)
+3. Output tabular
+
+**Output:**
+```
+12 endpoints across 3 groups:
+
+Auth (2)
+- POST /api/auth/login   — Authenticate user
+- POST /api/auth/logout  — Clear session
+
+Users (5)
+- GET    /api/users        — List users
+- POST   /api/users        — Create user
+- GET    /api/users/:id    — Get user by id
+- PATCH  /api/users/:id    — Update user
+- DELETE /api/users/:id    — Delete user
+
+Orders (5) ...
+```
+
+## Stale-index handling
+
+Before answering, check `.dw/intel/.last-refresh.json`:
+
+- If `updated_at` is more than 7 days old → prefix the answer with: `⚠ Index last refreshed YYYY-MM-DD (X days ago). Run /dw-map-codebase to refresh.`
+- If `.last-refresh.json` is absent → prefix with: `⚠ No refresh metadata. Index may be stale; run /dw-map-codebase.`
+
+Don't refuse to answer — return the best info available, but flag the staleness so the user can decide whether to trust it.
+
+## Fallback path (no `.dw/intel/`)
+
+If `.dw/intel/` doesn't exist at all:
+
+1. Check `.dw/rules/` (from `/dw-analyze-project` or `/dw-new-project` seeding)
+2. If `.dw/rules/index.md` exists, search there for the query keywords
+3. Otherwise, do a direct `grep -r` over the project source (excluding `node_modules`, `.git`, etc.)
+4. Suggest at the end: `Tip: run /dw-map-codebase to build a queryable index. Subsequent /dw-intel queries will be much faster.`
+
+## Don't
+
+- Don't fabricate paths or symbols not present in the index
+- Don't return "I don't know" without first trying the secondary file and grep fallback
+- Don't ignore stale-index warnings — surface them prominently
+- Don't dump the entire JSON of an intel file as the answer; synthesize and cite paths

package/scaffold/skills/dw-debug-protocol/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: dw-debug-protocol
+description: Use when investigating a bug — applies stop-the-line discipline plus a six-step triage (reproduce → localize → reduce → fix root cause → guard → verify) so you fix what's actually broken instead of papering over symptoms.
+---
+
+# Debug Protocol
+
+> **Inspired by** [`addyosmani/agent-skills/debugging-and-error-recovery`](https://github.com/addyosmani/agent-skills/tree/main/debugging-and-error-recovery) (MIT). Patterns and stop-the-line philosophy adapted from Addy Osmani's work; specific guidance and references rewritten to fit dev-workflow's bugfix and QA loops.
+
+The fastest path through a bug is the disciplined one. This skill encodes the discipline.
+
+## When this skill applies
+
+- Any failing test, runtime error, or "it works locally but not in CI" report.
+- Reproducing a user-reported issue.
+- A regression after a refactor or dependency bump.
+- An intermittent / non-reproducible bug (see `references/non-reproducible-strategy.md`).
+
+If you're tempted to "just try a fix and see," stop. Run the protocol below first.
+
+## The four core rules
+
+### 1. Stop the line
+
+The moment a bug is confirmed, stop adjacent work. Do not pile features on top of broken state. Branches stay frozen until the bug is reproduced and a fix path is identified — *or* explicitly downgraded ("not blocking, scheduled for later").
+
+See `references/stop-the-line.md` for when this rule bends.
+
+### 2. Reproduce before fixing
+
+Without a deterministic reproduction, you cannot know whether your "fix" worked. The reproduction is the hypothesis test. Even a flaky bug needs a *reproducible-enough* test (e.g., "fails 8/10 runs") before fixing.
+
+If you cannot reproduce: see `references/non-reproducible-strategy.md`. Don't fix on guess.
+
+### 3. Find the root cause, not the nearest cause
+
+The first place the stack trace lights up is rarely where the bug LIVES. The bug lives wherever the invariant was violated. Fixing the symptom (e.g., catching a `null` you shouldn't have produced) hides the real issue and makes the next bug worse.
+
+### 4. Guard against recurrence before declaring done
+
+Every fix produces an artifact: a regression test that proves the bug exists, then proves it's fixed. Without this artifact, the bug WILL come back during the next refactor.
+
+## The six-step triage
+
+Each bug runs through these six steps, in order. See `references/six-step-triage.md` for detail.
+
+| Step | Question | Output |
+|------|----------|--------|
+| 1. Reproduce | Can I trigger this on demand? | A failing test or repro script |
+| 2. Localize | Where does the invariant break? | A file:line where state goes wrong |
+| 3. Reduce | What's the smallest input that triggers it? | Minimal repro (1-3 lines if possible) |
+| 4. Fix root cause | Why is the invariant violated? Fix THAT. | Code change at the cause, not the symptom |
+| 5. Guard | What test would have caught this? | Regression test added to suite |
+| 6. Verify end-to-end | Does the original report scenario now pass? | Manual or scripted E2E proof |
+
+Do not skip steps. Skipping reduce → bigger fix than needed. Skipping guard → repeat bug in 3 weeks.
+
+## Error categorization
+
+Bugs cluster into a small number of categories. Knowing the category narrows where to look — see `references/error-categorization.md`:
+
+| Category | Typical symptom | Where to look first |
+|----------|-----------------|---------------------|
+| UI / render | Wrong pixels, missing element, click does nothing | Component tree, prop flow, conditional render |
+| Network / I/O | Timeout, 500, partial data | Request payload, headers, error path, retry |
+| State / data | Wrong value displayed, stale read | State management, cache invalidation, race |
+| Concurrency | "Sometimes fails", deadlock | Async order, locks, await placement |
+| Configuration | Works dev, fails prod | Env vars, secrets, build flags, infra config |
+| Logic | Branch returns wrong result | Guard conditions, off-by-one, boolean polarity |
+
+## Non-reproducible bugs
+
+Some bugs only happen in production, only on certain users, only at certain times. Don't fix them on intuition. The protocol in `references/non-reproducible-strategy.md` covers:
+
+- Timing/race conditions: instrument with logs first, fix second
+- Environment-specific: bisect by environment delta
+- State-dependent: capture user state at moment of failure
+- Frequency-dependent: deploy logging, wait for next occurrence
+
+A "fix" for an unreproduced bug is a guess. Mark it as such in the commit message.
+
+## Verification before declaring done
+
+A bug is fixed when:
+
+1. The repro from step 1 now passes.
+2. The regression test from step 5 was committed.
+3. Lint + tests + build are all GREEN.
+4. The original report scenario (E2E) was verified — by you, or with a screenshot/log/run trace if not directly reproducible.
+
+If any are missing, the bug is "fixed pending verification," not "fixed."
+
+## Integration with dev-workflow commands
+
+- `/dw-bugfix` runs this skill end-to-end. The bug report is decomposed into steps 1-6 and progressed atomically.
+- `/dw-fix-qa` uses this skill when QA findings are bug-shaped (failing scenario rather than missing feature). Each finding becomes a six-step run.
+- `/dw-code-review` flags fixes that skipped step 5 (no regression test) as REJECTED.
+
+## When to escalate / pair
+
+After 60 minutes stuck at step 2 (localize) or step 4 (root cause), surface the situation to the user:
+
+- "I've exhausted hypotheses A/B/C; here's what I tried and what's left."
+- Don't silently spin. Fresh eyes find what stuck eyes miss.
+
+This is not failure — it's protocol. Stuck > 1 hour is a signal, not a flaw.

package/scaffold/skills/dw-debug-protocol/references/error-categorization.md

@@ -0,0 +1,127 @@
+# Error categorization — symptom → cause matrix
+
+Before debugging, classify the bug. Wrong category = wasted hours. Most bugs sit in one of six categories; each has a typical hunting ground.
+
+## The six categories
+
+### 1. UI / rendering
+
+**Symptoms:** Wrong pixels, missing element, click does nothing, layout shift, hydration mismatch.
+
+**Hunting ground:**
+- Component tree: prop flow from root to leaf.
+- Conditional render guards: `{cond && <Foo />}` where `cond` is unexpectedly false (or truthy when 0).
+- CSS specificity / cascade collisions.
+- Server vs client mismatch (Next.js, hydration).
+- Event handler binding (lost `this`, stale closure capturing old state).
+
+**First check:** Open browser devtools → Elements panel → confirm the element exists in DOM. If yes, problem is CSS/layout. If no, problem is render path.
+
+**Often misclassified as:** State bug. Check the prop value at render time before chasing state.
+
+### 2. Network / I/O
+
+**Symptoms:** Timeout, 5xx response, partial data, "loading forever," CORS error.
+
+**Hunting ground:**
+- Request payload (DevTools Network tab → check what was actually sent).
+- Auth headers / cookies (missing, expired, wrong domain).
+- Server-side error (check the API logs, not just the client's view).
+- Retry/timeout configuration (too short = flaky; too long = perceived hang).
+- Idempotency: request retried in a way the server treated as new.
+
+**First check:** Reproduce in DevTools Network tab. Copy as cURL → run from terminal. If terminal request works, client config is wrong. If terminal also fails, server is wrong.
+
+**Often misclassified as:** Logic bug. Verify the request actually went out before assuming bug is in the response handler.
+
+### 3. State / data
+
+**Symptoms:** Wrong value displayed, stale read, "I updated it but it didn't change," off-by-one in collections.
+
+**Hunting ground:**
+- State management: where is the source of truth? How is it updated?
+- Cache invalidation: did the cache layer return stale data?
+- Race condition: did two updates arrive out of order?
+- Mutation vs replacement: did a deep mutation fail to trigger a re-render?
+- Derived state: is a computed value re-running when it should, or memoized too aggressively?
+
+**First check:** Log the state at three points — when it's set, when it's read, when it's rendered. The discrepancy reveals the layer with the bug.
+
+**Often misclassified as:** UI bug. The pixel is wrong because the data is wrong; fix the data.
+
+### 4. Concurrency
+
+**Symptoms:** "Sometimes fails," deadlock, race ("works locally, fails in CI"), out-of-order writes, lost update.
+
+**Hunting ground:**
+- Async boundaries: missed `await`, dangling promise, fire-and-forget that needed completion.
+- Locking: missing lock, lock held too long, lock granularity wrong.
+- Order assumptions: code assumes A finishes before B without enforcing it.
+- Test isolation: shared state between tests creating false dependency.
+
+**First check:** Add timing logs. If the bug rate changes when you add `setTimeout(0)` or `process.nextTick`, it's a concurrency bug.
+
+**Diagnostic patterns:**
+- Sleep-and-check: the bug disappears if you add 100ms delay → ordering issue.
+- Always-fails-on-fast-machine: missed async wait.
+- Always-fails-on-slow-machine: timeout too tight.
+- Fails 1/N runs: race condition; the rate gives clues to the window.
+
+**Often misclassified as:** "Just flaky, ignore." Concurrency bugs always have a cause. Re-running until green is hiding, not fixing.
+
+### 5. Configuration
+
+**Symptoms:** "Works in dev, fails in prod," "works on my machine," sudden behavior change after deploy.
+
+**Hunting ground:**
+- Environment variables: present? right value? expected name? leading/trailing whitespace?
+- Feature flags: toggled differently between environments?
+- Build flags: dev mode strips assertions; prod might not include polyfills.
+- Infra: different DB version, different Node version, different network topology.
+- Secrets: rotated, expired, wrong key.
+
+**First check:** Print the environment at startup (sans secrets) → diff dev vs prod. The diff often contains the bug.
+
+**Diagnostic command:** `env | sort` (or equivalent) at app entry, in both environments. Compare.
+
+**Often misclassified as:** Logic bug. The code is correct; the configuration is wrong.
+
+### 6. Logic
+
+**Symptoms:** Branch returns wrong result given correct input, incorrect calculation, off-by-one in iteration.
+
+**Hunting ground:**
+- Guard conditions: `>=` vs `>`, `&&` vs `||`, negation polarity.
+- Edge cases: empty array, single element, very large input, exact boundary value.
+- Type coercion: `"0"` is truthy in JS; `0 == false` but `0 !== false`.
+- Default values: a missing field falls back to `undefined`, not zero.
+- Floating point: `0.1 + 0.2 !== 0.3`.
+
+**First check:** Manually trace the function with the failing input. Often the bug is visible at line 3 of the function.
+
+**Often misclassified as:** State bug. The state is correct; the function uses it wrong.
+
+## Multi-category bugs
+
+Some bugs span categories. The clue: fixing only one category fixes the test but not production.
+
+Example: "Prod login fails."
+- Network: auth API returns 401 (real).
+- Configuration: prod has rotated secret; staging didn't.
+- State: client retains stale token in localStorage from before rotation.
+
+Fix all three or the bug returns next rotation.
+
+## Diagnostic shortcut: where did it last work?
+
+If the bug is new (not always existed):
+
+1. `git log` the affected files. What changed in the last 7 days?
+2. `git bisect` if the regression window is wide.
+3. Look at infra / dep / config changes (often the cause is outside source code).
+
+If the bug always existed:
+
+1. It's likely an edge case the original author didn't consider.
+2. Check the test fixtures — they probably hit the happy path only.
+3. Add the failing case to the test fixtures BEFORE fixing.