@brunosps00/dev-workflow 0.8.1 → 0.10.0

package/scaffold/skills/dw-git-discipline/references/trunk-based-pattern.md

@@ -0,0 +1,82 @@
+# Trunk-based development — short branches, fast integration
+
+Trunk-based means: `main` is always shippable, and most work lands on `main` within hours-to-days, not weeks. The opposite (long-lived feature branches) creates merge debt that compounds non-linearly.
+
+## The rules
+
+1. **Branches live 1-3 days, max a week.** Past a week, you're carrying risk.
+2. **Rebase from `main` daily.** A 1-day rebase is trivial; a 7-day one is a project.
+3. **Incomplete work hides behind a feature flag.** It can sit in `main` half-built without users seeing it.
+4. **Small PRs (≤400 lines diff).** Larger PRs get worse review quality and longer review cycles.
+5. **CI green before merge, always.** Yellow/red CI on `main` blocks everyone.
+
+## Why short branches
+
+A 7-day branch is not 7× the work of a 1-day branch. It's much worse:
+
+- **Compound merge cost.** Every day, the gap between your branch and `main` grows. Conflicts multiply non-linearly because the same files keep moving on both sides.
+- **Stale assumptions.** You wrote code against APIs/types from a week ago. The current version differs in ways you don't know.
+- **Lost context.** By day 7, you've forgotten why you wrote line 200 of file X. Reviews suffer.
+- **Coordination drag.** Other developers can't ship work that depends on your branch finishing.
+
+## Feature flags vs feature branches
+
+The classic question: "I'm building feature X but it's not ready to ship — won't merging it break things?"
+
+Two options:
+
+| Long branch | Feature flag |
+|-------------|--------------|
+| Code lives on a branch until ready | Code lives on `main` behind a `if (flag)` check |
+| Merge debt accumulates daily | No merge debt; integrates as you go |
+| Other devs can't see your changes | Other devs can read/review/depend on contracts |
+| Single big risky merge at the end | Many small low-risk merges |
+| Hard to demo / preview | Can demo to stakeholders by toggling flag |
+
+Feature flags win for almost every non-trivial feature. Costs:
+
+- Flag system needs to exist (LaunchDarkly, GrowthBook, env-based, or just a constant).
+- Flags have a lifecycle: introduce → ship code behind flag → enable → remove flag. The remove step is critical and often skipped.
+
+## When trunk-based bends
+
+- **Open-source / external contributors:** they can't push directly to `main`; long branches are inherent to fork-and-PR. Mitigation: small PRs, fast review, frequent merges.
+- **Compliance / audited environments:** PR + multi-stage review may take days regardless of branch life. Compress what you can.
+- **Big migrations / refactors crossing many modules:** can't always be flag-gated. Mitigation: break into many small PRs, each independently shippable, merged sequentially.
+
+In all bend cases, the SPIRIT of trunk-based still applies: minimize the gap between branch and `main`; integrate often; don't let drift compound.
+
+## The "let it sit on a branch" anti-pattern
+
+Common scenario: developer finishes feature X, opens PR, gets review delays, starts feature Y on a new branch from X (because Y depends on X), then X gets review feedback, X is rebased, Y now diverges from rebased X, X merges, Y has to rebase against the merged-X (different from branched-X), conflicts everywhere, Y stalls, X starts to bit-rot in production usage…
+
+Three fixes:
+
+1. **Don't stack branches.** If Y depends on X, wait for X to land. (Or merge X behind a flag and start Y from `main`.)
+2. **Cut review delays.** A PR sitting in review for 3 days is the bug; fix the review process, don't work around it.
+3. **Tighter scope.** If X is so big it takes 3 days to review, X should have been three PRs.
+
+## CI and trunk-based
+
+Trunk-based assumes CI is fast and reliable. If CI takes 45 minutes and is flaky:
+
+- Developers won't rebase frequently (too painful).
+- Branches drift, then conflicts on merge are big.
+- Pressure mounts to bypass CI ("just merge it, CI's broken anyway").
+
+Fixes happen in two directions:
+
+- Make CI fast (under 10 minutes ideally; under 20 acceptable).
+- Make CI reliable (flaky tests are bugs; fix or remove them).
+
+A team that can't trust CI cannot run trunk-based effectively.
+
+## Trunk-based + feature flags + atomic commits
+
+These three disciplines compound:
+
+- **Atomic commits** make rebases and reverts surgical.
+- **Trunk-based** keeps branches short, so rebases are tiny.
+- **Feature flags** decouple "code in main" from "feature live for users."
+
+Together: you can ship work daily, revert any single change without unwinding others, and toggle features without redeploys. This is the working norm for high-velocity teams; it's not optional discipline, it's load-bearing.

package/scaffold/skills/dw-memory/SKILL.md

@@ -155,8 +155,7 @@ When flagged for compaction, apply inline:
 
 - `/dw-run-task` — reads memory before coding; updates `<N>_memory.md` during; runs promotion test + updates `MEMORY.md` at the end.
 - `/dw-run-plan` — runs promotion + compaction between tasks, so each task starts with clean shared state.
-- `/dw-autopilot` — threads memory through every phase (brainstorm → PRD → techspec → tasks → execution).
-- `/dw-resume` — reads `MEMORY.md` first to reconstitute cross-session context, then the active task's memory.
+- `/dw-autopilot` — threads memory through every phase (brainstorm → PRD → techspec → tasks → execution); on re-invocation reads `MEMORY.md` first to reconstitute cross-session context.
 
 Callers should mention this skill in their "Skills Complementares" section.
 

package/scaffold/skills/dw-simplification/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: dw-simplification
+description: Disciplined code simplification — understand WHY code exists before changing it (Chesterton's Fence), preserve behavior exactly, prefer clarity over cleverness, scope to recent changes. Used by /dw-code-review and /dw-refactoring-analysis. Adapted from addyosmani/agent-skills (MIT).
+allowed-tools:
+  - Read
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+---
+
+# dw-simplification
+
+Behavioral discipline for simplifying code without breaking it. The trap of refactoring is removing something that "looked unused" but was load-bearing for an edge case nobody documented. This skill enforces a protocol that prevents that class of regression.
+
+## When to Use
+
+Read this skill when:
+
+- `/dw-code-review` flagged a complexity issue (deep nesting, long function, duplication).
+- `/dw-refactoring-analysis` proposed a simplification target.
+- The user explicitly asks to "clean this up" / "simplify X".
+- During `/dw-run-task` if the implementation accidentally produced complex code that wants pre-commit cleanup.
+
+Do NOT use when:
+
+- The complexity is intentional (e.g., performance hot path with optimization comments — leave alone).
+- You're simplifying code you didn't just write or read recently — scope creep.
+- Tests are missing for the area — without tests, "preserve behavior exactly" is unverifiable. Add tests first, then simplify.
+
+## The Five Rules
+
+### 1. Chesterton's Fence — understand BEFORE changing
+
+Before removing or rewriting any code, answer three questions:
+
+1. **What does it actually do?** Run/trace it; don't guess from the name.
+2. **Why was it added?** Check `git log --follow <file> --oneline` and look at the introducing commit's message + PR. Often there's a reason.
+3. **What breaks if it's gone?** Search for callers. Run the test suite to find what changes.
+
+If you can't answer all three, you're not ready to simplify. Get answers first.
+
+Concrete cases where Chesterton's Fence saves you:
+- A "redundant" early return that handles a race condition.
+- A "useless" type cast that fixes a compiler bug on a specific platform.
+- A "duplicated" check that exists for clarity at the API boundary.
+- A "dead" branch that runs only with a feature flag enabled in production.
+
+### 2. Preserve behavior exactly
+
+The test for "did I simplify or did I change?" is: do the existing tests still pass without modification? If yes, behavior is preserved. If you needed to update tests, you changed behavior — that's a refactor, not a simplification.
+
+When tests are inadequate to confirm behavior preservation, write tests FIRST that document current behavior, then simplify against them. This is the test characterization technique.
+
+### 3. Follow project conventions
+
+Match what the project already does. If files use 2-space indent and arrow functions, your simplified version uses 2-space indent and arrow functions — even if you'd prefer 4-space and `function`. Conventions matter more than personal preference; consistency is itself a form of clarity.
+
+Project conventions live in `.dw/rules/<module>.md` (from `/dw-analyze-project`). Read first.
+
+### 4. Prefer clarity over cleverness
+
+Rules of thumb:
+
+- A line of code that takes 30 seconds to understand is worse than three lines that take 5 seconds each.
+- A "neat trick" with comments is uglier than the boring obvious code without comments.
+- Optimization that costs readability needs measurement (`dw-performance` skill territory) — without numbers, prefer the readable version.
+- "Magic" that requires knowing a language feature most teammates haven't used is anti-clarity. Use it only when the alternative is genuinely worse.
+
+### 5. Scope to recent changes
+
+Don't go simplifying old code while you're "in there". The risk-to-benefit ratio of changing 5-year-old battle-tested code is bad. Limit simplification to:
+
+- Code you just wrote in this session.
+- Code your current task touches.
+- Code with explicit recent breakage (e.g., a bug just fixed that revealed bad structure).
+
+Out of scope: any other code, no matter how ugly. Open a task / ADR for those instead of fixing in-flight.
+
+## Pattern recognition
+
+Frequent simplification targets — but apply Rules 1-5 before acting:
+
+| Smell | Healthy refactor | When NOT to refactor |
+|-------|------------------|----------------------|
+| Deep nesting (4+ levels) | Early returns / guard clauses | When the nesting maps to a real domain hierarchy (e.g., visitor pattern) |
+| Long function (>50 lines) | Extract method | When the "natural" extraction would produce 3-4 single-call helpers — you're trading complexity for indirection |
+| Generic name (`data`, `info`, `helper`) | Rename to specific | When the function genuinely processes generic input (e.g., a serializer middleware) |
+| Duplication (same 5 lines twice) | Extract to function/constant | When the duplication is by design (e.g., independent business rules that may diverge) |
+| `if/elif/else` chain (5+ branches) | Strategy pattern / lookup table | When the branches are naturally exclusive states with branch-specific logic |
+
+## Rule of 500 — automate large refactors
+
+If a simplification touches >500 lines, **don't do it manually**. Use:
+
+- AST-based codemods (`jscodeshift` for JS/TS, `libcst` for Python, Roslyn for C#, `rust-analyzer` for Rust).
+- IDE-driven refactoring tools (Rename Symbol, Extract Method, Inline Variable).
+- Search-and-replace ONLY when the pattern is unambiguous and verifiable.
+
+Manual edits across hundreds of lines are how subtle bugs creep in.
+
+## Verification protocol
+
+Before committing the simplification:
+
+```
+1. Lint passes:    pnpm lint  / ruff check  / dotnet format --verify-no-changes  / cargo clippy
+2. Tests pass:     pnpm test  / pytest      / dotnet test                         / cargo test
+3. Build passes:   pnpm tsc --noEmit / mypy / dotnet build                         / cargo check
+```
+
+All three GREEN. If any is RED, the simplification broke something — revert or fix.
+
+For changes that altered cyclomatic complexity, optionally run a complexity analyzer to confirm the metric actually improved (some "simplifications" make code more complex by spreading it).
+
+## How `dw-code-review` uses this
+
+In the formal Level 3 review (post-Level 2 chain from `dw-review-implementation`), code-review flags complexity issues using the patterns above. Each flagged issue references this skill: "consider simplifying via guard clauses; apply Chesterton's Fence — verify why the nested check exists before flattening."
+
+## How `dw-refactoring-analysis` uses this
+
+The analysis catalogs code smells (Fowler vocabulary). For each smell, the proposed refactor cites:
+1. Which simplification rule applies (early return / extract method / lookup table / etc.).
+2. Whether Chesterton's Fence concerns block the refactor (existing tests inadequate? no recent commits explaining the structure? → flag as YELLOW, don't act).
+
+## Anti-patterns
+
+1. Simplifying code you didn't read carefully. The "obvious dead code" is often someone's hard-won bug fix.
+2. Skipping the test gate "because the change is small". Small changes break things too.
+3. Changing whitespace + naming + structure in one commit. Atomic: each commit one kind of change.
+4. Refactoring while touching unrelated code (mix-in scope creep). Open a separate task.
+5. Personal-style refactors disguised as simplification. Project conventions > your preferences.
+
+## References
+
+- `references/chestertons-fence.md` — the protocol in detail; case studies of "obvious-but-wrong" removals.
+- `references/complexity-metrics.md` — when each metric (cyclomatic, cognitive, depth, fanout) actually matters; how to measure cheaply.
+- `references/behavior-preserving.md` — characterization tests, refactor with test gate, rollback patterns, codemod tooling per language.
+
+## Inspired by
+
+Adapted from [`addyosmani/agent-skills/code-simplification`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT license). Core principles (Chesterton's Fence, behavior preservation, scope discipline, Rule of 500) preserved. dev-workflow integration: invoked by `dw-code-review` and `dw-refactoring-analysis` via Complementary Skills.

package/scaffold/skills/dw-simplification/references/behavior-preserving.md

@@ -0,0 +1,148 @@
+# Behavior-preserving refactor — the test gate that protects you
+
+The promise of simplification: the code is cleaner; nothing observable changed. The risk: you broke a subtle behavior nobody had a test for.
+
+## The test gate
+
+Before simplifying ANY non-trivial code, ensure tests cover what you're about to change. Three cases:
+
+### Case A — tests exist and pass
+
+Run them. They pass before, they pass after. Done.
+
+### Case B — tests exist but are incomplete
+
+Run them. They pass before. Apply your simplification. They still pass — but you don't trust them to catch your specific concern.
+
+Action: write a characterization test FIRST that pins the behavior you're worried about. Then simplify.
+
+### Case C — no tests at all
+
+Don't simplify. The "preserve behavior exactly" claim is unverifiable. Either:
+- Write characterization tests first (see below), then simplify.
+- Or open a separate task ("add tests for X") and don't touch the code now.
+
+## Characterization tests
+
+A characterization test documents what the code currently does, without claiming whether that's correct. It's a freeze of behavior at a point in time.
+
+Pattern:
+
+```javascript
+// Characterization test — not asserting CORRECTNESS,
+// asserting BEHAVIOR-AT-TIME-OF-WRITING.
+describe('legacyFormatter (characterization)', () => {
+  it('handles empty input by returning "(none)"', () => {
+    expect(legacyFormatter('')).toBe('(none)');
+  });
+
+  it('preserves trailing whitespace in output', () => {
+    expect(legacyFormatter('hello ')).toBe('hello ');
+  });
+
+  it('returns null when input is undefined', () => {
+    expect(legacyFormatter(undefined)).toBe(null);
+  });
+});
+```
+
+Goal: capture the WEIRD behaviors. Boring behaviors don't need tests; nobody breaks them. The weird parts are the load-bearing ones.
+
+## How to find weird behaviors to characterize
+
+1. Run the function with a range of inputs (empty, null, undefined, very long, special chars, edge values).
+2. Note any output that surprised you. That's a weird behavior.
+3. Write a test that pins it.
+
+Example session:
+
+```bash
+node -e "console.log(JSON.stringify(require('./src/legacy').format('')))"
+# Output: "(none)"   ← weird, document it.
+
+node -e "console.log(JSON.stringify(require('./src/legacy').format('hello ')))"
+# Output: "hello "   ← preserves trailing whitespace? unusual, document.
+
+node -e "console.log(JSON.stringify(require('./src/legacy').format(undefined)))"
+# Output: null      ← returns null not "(none)" for undefined? document.
+```
+
+Tests written; now you can simplify. If after your refactor any of these tests fail, you broke behavior — even if your version "looks better".
+
+## Refactor with the test gate
+
+```
+1. Run tests → GREEN (baseline)
+2. Apply simplification (one logical change)
+3. Run tests → expect GREEN
+   - If RED → revert, understand why, retry differently
+4. Commit (atomic — one simplification per commit)
+5. Repeat for next simplification
+```
+
+DO NOT batch multiple simplifications into one commit. If something breaks, you can't bisect which change caused it.
+
+## Rollback patterns
+
+If the simplification went wrong AND the issue surfaces only post-merge:
+
+```bash
+git revert <simplification-sha>
+```
+
+Atomic commits make this clean. The revert is one commit; tests pass again; you can investigate at leisure.
+
+If multiple simplifications were stacked and one broke:
+
+```bash
+# Find which one
+git bisect start
+git bisect bad HEAD
+git bisect good <known-good-sha>
+# Run tests at each step
+```
+
+Bisect requires that EACH commit be testable in isolation — another reason for atomic commits.
+
+## Codemod tooling per language
+
+For refactors >500 lines, manual edits are dangerous. Use AST-based codemods:
+
+### TypeScript / JavaScript
+- **jscodeshift** — Facebook's AST-based codemod runner. Many community codemods at `npmjs.com/package/<framework>-codemods`.
+- **ts-morph** — programmatic TypeScript AST manipulation. Good for one-off refactors.
+- **ESLint --fix** — for any rule that has a fixer (most of them); narrow scope.
+
+```bash
+# Run a community codemod
+npx jscodeshift -t ./codemods/extract-method.js src/
+```
+
+### Python
+- **libcst** — Instagram's concrete syntax tree library. Preserves comments + formatting.
+- **ast** module + custom walker for simpler cases.
+- **Ruff --fix** for known auto-fixable rules.
+
+### C# / .NET
+- **Roslyn analyzers + code fixes** — write a custom analyzer with a fix provider; runs across the solution.
+- **Visual Studio Refactor menu** for IDE-driven multi-file renames/extractions.
+
+### Rust
+- **rust-analyzer** has refactor support: rename, extract function, inline variable.
+- **rustfmt + clippy --fix** for style/idiom-level fixes.
+
+## Don't
+
+- Don't simplify and update tests in the same commit. The test changes hide what you changed in the code.
+- Don't consider lint passing as "behavior preserved". Lint catches syntax; tests catch behavior.
+- Don't trust "no test failed therefore behavior preserved" if test coverage is <60%. Add tests first.
+- Don't pre-emptively simplify for a future hypothetical maintainer. Simplify when you have a present reason (a bug, a read-time confusion).
+
+## When the refactor is too risky
+
+If steps 2-3 of the test gate consistently fail (you can't pin the behavior, or your simplification keeps breaking subtle things):
+
+- The code is genuinely complex for a reason; leave it.
+- Or: rewrite-with-tests as a separate, larger task — not in-flight simplification.
+
+The right call sometimes is "this code is ugly but works; ship around it; revisit when you have hours, not minutes."

package/scaffold/skills/dw-simplification/references/chestertons-fence.md

@@ -0,0 +1,152 @@
+# Chesterton's Fence — understand WHY before changing
+
+> "If you find a fence in the middle of a field, don't tear it down until you know why it was put there." — G.K. Chesterton (paraphrased)
+
+In code, the "fence" is anything that looks unnecessary on first read. Most code that looks unnecessary is actually load-bearing for a case the casual reader hasn't encountered.
+
+## The protocol
+
+Before removing or rewriting anything:
+
+### 1. What does it actually do?
+
+Don't trust the name. Names lie. Names get repurposed. Read the body. Trace the call graph.
+
+If you can't say in one sentence what the code does (not what it's named, what it DOES), you don't yet understand it.
+
+### 2. Why was it added?
+
+```bash
+# When did this line/block enter the codebase?
+git log -L <start>,<end>:<file> --oneline | head -5
+
+# Or for a whole file
+git log --follow --oneline <file> | head -10
+
+# Read the introducing commit
+git show <commit-hash>
+```
+
+The commit message + PR title + linked issue often have the rationale. Common findings:
+
+- "Fix race condition when X happens during Y" — the seemingly redundant check is the fix.
+- "Workaround for [framework] bug #1234" — the weird code is a workaround.
+- "Required for [external system] compatibility" — the cast/wrapper exists for a reason.
+- "TODO: simplify after we deprecate Y" — there's an explicit plan, follow it.
+
+### 3. What breaks if it's gone?
+
+```bash
+# Find callers
+rg -F "<symbol>" --type <lang>
+
+# Run the test suite
+<test-runner>
+```
+
+If tests pass with the code removed, it might be safe — but tests have gaps. Cross-check with:
+- Search the whole codebase for the symbol/string
+- Check `.dw/intel/files.json` for `imports` referencing it
+- For exported symbols, check downstream consumers (other repos, npm, etc.)
+
+If even one of the three answers is "I don't know", DON'T REMOVE.
+
+## Case studies
+
+### Case 1 — "Redundant" early return
+
+Code:
+
+```python
+def process(item):
+    if item is None:
+        return
+    if item.id is None:
+        return
+    # ...rest...
+```
+
+Looks like the second `if` could merge into the first via `if item is None or item.id is None`. But:
+
+- `item is None` is a system error (caller passed None).
+- `item.id is None` is a domain state (item not yet persisted).
+
+The two cases warrant different downstream behavior in the future (e.g., logging the second but not the first). Merging them collapses the distinction. Chesterton's Fence: leave alone unless you also remove the future flexibility intentionally.
+
+### Case 2 — "Useless" type cast
+
+Code:
+
+```typescript
+const value = (someApi.fetch() as unknown) as MyType;
+```
+
+Looks like `as MyType` would suffice. But the double-cast was added because the API's actual return type is incompatible with `MyType` and a direct cast errors. Removing the `as unknown` step breaks compilation.
+
+The fix isn't to remove the double-cast; it's to either fix `MyType` (if the API is right) or fix the API typings (if `MyType` is right). Chesterton's Fence: read the commit message — usually says "compiler workaround for incompatible types".
+
+### Case 3 — "Duplicated" validation
+
+Code:
+
+```javascript
+function createUser(payload) {
+  if (!payload.email) throw new ValidationError('email required');
+  // ...
+}
+
+function updateUser(id, payload) {
+  if (!payload.email) throw new ValidationError('email required');
+  // ...
+}
+```
+
+Looks like duplication; "extract" to `validatePayload(payload)`. But:
+
+- `createUser` requires email.
+- `updateUser` may eventually allow email-less updates (e.g., just change name).
+
+Today they happen to share validation; tomorrow they might not. The "duplication" preserves independence of evolution. Don't extract a shared validator until at least 3 callers exist with truly identical rules.
+
+### Case 4 — "Dead" branch
+
+Code:
+
+```typescript
+if (process.env.LEGACY_MIGRATION_MODE === 'true') {
+  return legacyTransform(input);
+}
+return modernTransform(input);
+```
+
+Looks dead because nobody sets `LEGACY_MIGRATION_MODE` in test/dev. But:
+
+- Production sets it on the data-import service.
+- The migration runs once a quarter when new historical data lands.
+
+Removing the branch means the next quarterly migration breaks silently. Chesterton's Fence: check production env vars / feature flags / runtime configs before deleting "dead" branches.
+
+## When you DO act
+
+After all three protocol steps, if:
+
+1. You understand what the code does.
+2. You know why it was added (and the reason no longer applies, or you have evidence it never applied).
+3. You've verified nothing breaks.
+
+THEN you can simplify. Cite the rationale in the commit message:
+
+```
+refactor(auth): remove fallback to legacy session API
+
+The fallback was added in 2022-04 for compatibility with the v1
+session service, which was decommissioned in 2024-09 (PR #4567).
+No callers reference the legacy code path; tests confirm the
+modern path covers all scenarios. Removed.
+```
+
+Future maintainers can see why the change was safe. They can also see — if it turns out NOT to be safe — exactly what assumption was wrong.
+
+## Anti-pattern
+
+Removing code because "it looks unused" without doing the three steps. Speed is not the goal; correctness is. A 30-minute investigation to avoid a 3-day production rollback is a great trade.

package/scaffold/skills/dw-simplification/references/complexity-metrics.md

@@ -0,0 +1,147 @@
+# Complexity metrics — when each one actually matters
+
+Metrics are signal, not verdict. A function with cyclomatic complexity 12 isn't automatically "bad" — but it's worth a second look. This file describes the four common metrics, when each matters, and how to measure cheaply.
+
+## The four metrics
+
+### 1. Cyclomatic complexity
+
+Counts independent paths through a function. Each `if`, `else`, `for`, `while`, `case`, `&&`, `||`, `?:` adds one.
+
+| Score | What it means | Action |
+|-------|---------------|--------|
+| 1-5 | Simple, easily testable | Leave alone |
+| 6-10 | Moderate; usually fine | Test thoroughly |
+| 11-20 | Complex; review case-by-case | Strong candidate to simplify |
+| 21+ | Very complex; high bug rate empirically | Definitely simplify (or split) |
+
+Caveat: long switch/match statements over enum values can score high but be naturally clear. Cyclomatic complexity over-penalizes them.
+
+### 2. Cognitive complexity
+
+Counts how hard the function is to **understand** (not just trace through). Nesting amplifies; flat structures don't. `goto`, `break N levels`, and recursion add weight.
+
+This metric correlates better with bug rate than cyclomatic. Most modern linters compute it (SonarQube, ESLint with `sonarjs`, `radon` for Python).
+
+| Score | Action |
+|-------|--------|
+| 0-9 | Fine |
+| 10-15 | Review |
+| 16+ | Refactor |
+
+### 3. Nesting depth
+
+Counts the maximum depth of `if`/`for`/`try` nesting in a function.
+
+| Depth | Action |
+|-------|--------|
+| 1-2 | Fine |
+| 3 | Acceptable; consider early returns |
+| 4 | Smell; usually flatten via guard clauses |
+| 5+ | Almost always refactor |
+
+Easiest to fix via early returns:
+
+```javascript
+// Before — depth 4
+function process(req) {
+  if (req) {
+    if (req.user) {
+      if (req.user.active) {
+        if (req.body) {
+          return doWork(req.body);
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// After — depth 1
+function process(req) {
+  if (!req) return null;
+  if (!req.user) return null;
+  if (!req.user.active) return null;
+  if (!req.body) return null;
+  return doWork(req.body);
+}
+```
+
+### 4. Fan-out (outgoing dependencies)
+
+Number of distinct other modules a function calls. High fan-out = many touchpoints; refactor risky.
+
+| Fan-out | Action |
+|---------|--------|
+| 0-3 | Fine |
+| 4-7 | Acceptable |
+| 8+ | Function probably has too many concerns; consider splitting |
+
+## When each metric matters
+
+| Symptom | Metric to check |
+|---------|-----------------|
+| "This function has a lot of `if`s" | Cyclomatic + nesting depth |
+| "I keep getting lost reading this" | Cognitive complexity |
+| "Tests miss edge cases" | Cyclomatic (each path needs a test) |
+| "Refactor keeps breaking adjacent code" | Fan-out + fan-in |
+| "Function is 200 lines" | Length + nesting (length alone is weak signal) |
+
+## How to measure cheaply
+
+### TypeScript / JavaScript
+
+```bash
+# ESLint with sonarjs plugin
+npx eslint --rule 'sonarjs/cognitive-complexity: ["error", 15]' src/
+
+# Or per-file analysis
+npx complexity-report src/foo.ts
+
+# Bundle analysis adjacent
+npx eslint --rule 'complexity: ["warn", 10]' src/
+```
+
+### Python
+
+```bash
+# Radon — cyclomatic + cognitive
+pip install radon
+radon cc src/ -a    # cyclomatic, average per file
+radon mi src/       # maintainability index
+
+# Or via ruff
+ruff check --select C901 src/
+```
+
+### C# / .NET
+
+```bash
+# Code metrics via Roslyn
+dotnet build /p:CodeAnalysisRuleSet=...
+# Or in Visual Studio: Analyze → Calculate Code Metrics
+```
+
+### Rust
+
+```bash
+# Clippy + complexity lints
+cargo clippy -- -W clippy::cognitive_complexity
+
+# Or rust-code-analysis CLI
+rust-code-analysis-cli -m -p src/
+```
+
+## Don't
+
+- **Don't chase a score.** "Cyclomatic 9 vs 10" is meaningless. The function either reads clearly or doesn't.
+- **Don't refactor purely to lower a number.** If `cognitive_complexity: 16` flags a switch over 16 enum cases, leaving it alone is fine.
+- **Don't measure the whole repo at once and act on the top 100.** Most will be false positives. Focus on functions you're touching.
+- **Don't ignore the trend.** A file going from average cognitive 8 → 14 over 6 months is a smell, even if no individual function crossed the threshold.
+
+## Healthy use of metrics
+
+- Run on PRs that touched complex code; flag if a function moved to a worse bucket.
+- Run on long-lived hot files quarterly; spot drift.
+- Set CI gates ONLY at gross thresholds (e.g., cognitive >25), not at edge thresholds (>10).
+- Treat metrics as conversation starters, not pass/fail gates.