@brunosps00/dev-workflow 0.9.0 → 0.10.0

package/scaffold/skills/dw-git-discipline/references/atomic-commits-discipline.md

@@ -0,0 +1,158 @@
+# Atomic commits — one intent per commit
+
+A commit is atomic if it represents exactly one logical change. Atomic commits are the foundation of `git bisect`, `git revert`, code review quality, and reading history six months later.
+
+## The single-intent rule
+
+If your commit message naturally contains "and" connecting two things — that's two commits.
+
+| Bad subject | Better |
+|-------------|--------|
+| `feat: add login form and fix navbar bug` | Two commits: `feat(login): add form`, `fix(nav): correct mobile menu` |
+| `refactor: extract user service and add caching` | Two commits: `refactor(user): extract service`, `feat(user): add result cache` |
+| `chore: update deps and reformat` | Two commits: `chore(deps): bump foo to 2.0`, `style: apply prettier sweep` |
+| `fix: handle null and add tests` | Two commits: `test(payment): cover null amount case`, `fix(payment): handle null amount` (or merge tests + fix when they're the same logical change — see below) |
+
+**Exception:** if you fix a bug AND add the regression test for it, those belong in ONE commit. The test proves the bug and proves the fix; separating them loses the link.
+
+## Refactor vs feature: always separate
+
+The most common atomicity violation: refactoring "while I'm in here" alongside a feature.
+
+Bad:
+```
+feat(orders): add bulk-order export AND extract OrderRepository
+```
+
+Good:
+```
+refactor(orders): extract OrderRepository (no behavior change)
+feat(orders): add bulk-order export endpoint
+```
+
+Why: when bulk-order export turns out to have a bug 2 months later, `git bisect` lands on the second commit. The first commit is a clean prior baseline you can compare against. If they were combined, the refactor's surface area dilutes the diagnosis.
+
+## Practical: how to make commits atomic
+
+When you find yourself with mixed changes in the working directory:
+
+```bash
+# 1. See what's changed
+git status
+git diff
+
+# 2. Stage just the refactor (no behavior change)
+git add -p   # interactive — pick hunks one by one
+# Or stage specific files:
+git add src/orders/repository.ts
+
+# 3. Verify what's staged matches one logical intent
+git diff --cached
+
+# 4. Commit
+git commit -m "refactor(orders): extract OrderRepository (no behavior change)"
+
+# 5. Stage the feature
+git add src/orders/bulk-export.ts src/orders/__tests__/bulk-export.test.ts
+
+# 6. Commit
+git commit -m "feat(orders): add bulk-order export endpoint"
+```
+
+`git add -p` is the workhorse for unmixing changes. Practice it.
+
+## Commit message structure
+
+Conventional Commits format:
+
+```
+type(scope): subject
+
+body — explains WHY, not what (the diff already shows what)
+
+Footer: BREAKING CHANGE, Refs, Co-Authored-By
+```
+
+**Type vocabulary:**
+
+| Type | Use for |
+|------|---------|
+| `feat` | New user-facing capability |
+| `fix` | Bug fix |
+| `refactor` | Code change with NO behavior change |
+| `perf` | Behavior unchanged but faster |
+| `docs` | Docs-only |
+| `test` | Test additions/changes only |
+| `style` | Formatting, no semantic change |
+| `chore` | Build, deps, config, no source change |
+| `ci` | CI pipeline changes only |
+| `build` | Build system changes |
+
+**Subject line rules:**
+- ≤72 chars
+- Imperative ("add" not "added", "fix" not "fixes")
+- No trailing period
+- Lowercase after the colon
+
+**Body rules:**
+- Wrap at 72-100 chars per line
+- Blank line between subject and body
+- WHY > WHAT
+- Reference issues, PRDs, ADRs when relevant
+
+## When to write a body
+
+You don't need a body for trivial changes. You need one when:
+
+- The reason for the change isn't obvious from the diff (e.g., a workaround for a bug in a dependency).
+- The change addresses an issue with non-obvious consequences (e.g., performance, security).
+- The change is a deliberate design choice over alternatives (briefly note the rejected option).
+- The change has a non-obvious blast radius.
+
+A good rule: if a future maintainer would say "huh, why?" reading the diff, write a body.
+
+## What goes in the footer
+
+- `BREAKING CHANGE: <explanation>` — for breaking-change commits.
+- `Refs #123` — issue reference.
+- `Co-Authored-By: Name <email>` — for pair work or AI assistance.
+
+## Bisect-friendly commits
+
+For `git bisect` to work, every commit must:
+- Build
+- Pass tests
+- Be a coherent state (not "WIP, half-implemented")
+
+If you can't bisect through your branch, the commits aren't atomic enough. Squash before merging is acceptable; intra-branch WIP commits get rebased away before push.
+
+## What to do with WIP / "save point" commits
+
+Local WIP is fine. Pushed WIP is not.
+
+Workflow:
+1. Make many small commits as you work (saves your progress).
+2. Before pushing OR before opening PR, `git rebase -i origin/main` to reorganize:
+   - Squash WIP commits into their logical parent.
+   - Drop accidental commits.
+   - Reorder so refactor comes before feature.
+   - Edit messages.
+3. Push the cleaned history.
+
+After pushing, no rewrites unless explicitly authorized — others may have pulled.
+
+## Common atomic-commit mistakes
+
+- **"Tiny extra fix" piggy-backed.** "While I was in there" → separate commit.
+- **Reformat sweep mixed with logic change.** Apply formatter as its own commit BEFORE making logic changes.
+- **Test fixture changes mixed with code changes.** If the fixture change is just to support the new code, fine — keep together. If the fixture was wrong before and you're fixing it, separate commit.
+- **Lockfile churn separate from intent.** Sometimes lockfile updates accompany intentional dep bumps; that's fine. But noisy lockfile changes from running `npm install` for unrelated reasons → revert.
+- **Generated file diffs mixed in.** Generated files (build artifacts, generated types) should regenerate from source automatically; don't commit them by hand alongside source changes if you can avoid it.
+
+## What atomic commits unlock
+
+- `git bisect` finds the exact commit that broke X — and that commit is small enough to inspect quickly.
+- `git revert <sha>` removes ONE feature without unwinding others.
+- Code review focuses: each commit reviewed in isolation makes a tight discussion possible.
+- Cherry-picking to other branches works cleanly when the change is one thing.
+- Commit messages become reliable changelog material.

package/scaffold/skills/dw-git-discipline/references/branch-hygiene.md

@@ -0,0 +1,150 @@
+# Branch hygiene — naming, lifetime, rebase vs merge
+
+Branches are conversations between developers. Names, lifetimes, and integration choices shape that conversation.
+
+## Branch naming conventions
+
+Format: `<type>/<scope>` or `<type>/<scope>-<short-description>`
+
+| Prefix | When |
+|--------|------|
+| `feat/` | New user-facing capability |
+| `fix/` | Bug fix |
+| `refactor/` | No behavior change, internal restructure |
+| `perf/` | Performance improvement |
+| `chore/` | Build, deps, config |
+| `docs/` | Documentation only |
+| `test/` | Test additions or fixes |
+| `experiment/` | Spike / exploration; usually NOT merged |
+| `hotfix/` | Urgent production fix |
+| `release/` | Release preparation (if your team uses release branches) |
+
+Rules:
+- Lowercase, kebab-case.
+- ≤40 characters total.
+- Match the prefix to the dominant change type if mixed.
+- Include a PRD/issue reference when one exists: `feat/prd-user-onboarding`, `fix/issue-1234-login-loop`.
+
+Examples:
+
+| Good | Bad |
+|------|-----|
+| `feat/user-onboarding` | `feature/UserOnboarding` (capitalized) |
+| `fix/login-redirect-loop` | `bug-fix-stuff` (no prefix, vague) |
+| `refactor/extract-user-service` | `mybranch` (meaningless) |
+| `chore/bump-react-19` | `update-deps-and-tests` (multi-intent in name) |
+
+## Branch lifetime
+
+| Branch type | Target lifetime |
+|-------------|-----------------|
+| `feat/` for normal feature | 1-3 days |
+| `fix/` for normal bug | hours to 1 day |
+| `hotfix/` | hours, ship same day |
+| `refactor/` for small refactor | hours to 1 day |
+| `refactor/` for major refactor | break into multiple `refactor/`+ branches, each 1-3 days |
+| `experiment/` | as long as needed, but NOT merged to main without conversion |
+| `release/` | until release ships |
+
+A branch older than a week is a smell. Either:
+- It's blocked on review (fix the review process).
+- It's too big (split it).
+- It should have been a feature flag on `main` (kill the branch, do it on main).
+
+## Daily integration with `main`
+
+While on a branch, integrate from `main` daily:
+
+```bash
+git fetch origin
+git rebase origin/main   # preferred for personal branches
+# OR
+git merge origin/main    # acceptable for shared branches
+```
+
+Why daily:
+- 1 day of drift = trivial conflicts.
+- 7 days of drift = cascading conflicts; same files changed on both sides multiple times.
+- Conflicts caught daily are individually small; conflicts caught at PR time are an avalanche.
+
+## Rebase vs merge
+
+| Situation | Choice |
+|-----------|--------|
+| Personal branch, never shared | Rebase. Linear history. |
+| Shared branch (others have pulled) | Merge. Rebase rewrites history; collaborators' branches diverge. |
+| Pulling latest `main` into your active feature branch | Rebase, IF nobody else has pulled your branch yet. |
+| Merging your feature into `main` via PR | Whatever the team standard is. Squash-merge is fine if commits weren't atomic; preserve commits if they were. |
+
+Rule of thumb: **rebase what's yours; merge what's shared.**
+
+## When NOT to force-push
+
+After a `git rebase`, the branch's history is rewritten — you must force-push to update the remote. This is FINE on a branch only YOU touch. It is BAD on shared branches because:
+
+- Collaborators have pulled the old history; their next pull will conflict in confusing ways.
+- Open PRs against the old SHAs may show garbled diffs.
+- Reviewers lose context if they linked to a specific SHA.
+
+Discipline:
+- `git push --force-with-lease` on personal branches: OK.
+- `git push --force` (without `with-lease`): never — too dangerous.
+- Force-push to `main` / `master` / `production` / shared release branches: only with explicit authorization, ideally never.
+
+## Cleanup: deleting merged branches
+
+After a branch merges:
+
+```bash
+# Delete locally
+git branch -d feat/user-onboarding
+
+# Delete remotely (most platforms auto-delete on PR merge)
+git push origin --delete feat/user-onboarding
+```
+
+A repo with hundreds of stale branches is noise. Most platforms (GitHub, GitLab) auto-delete on merge — enable that setting if you can.
+
+## Stale branch audit
+
+Once a quarter (or whenever the branch list gets noisy):
+
+```bash
+# List branches not merged to main, sorted by date
+git for-each-ref --sort=-committerdate refs/remotes/origin --format='%(committerdate:short) %(refname:short)' | head -50
+```
+
+Anything older than 60 days that hasn't merged: ask the owner — close, finish, or delete.
+
+## Hotfix branches
+
+When prod breaks and you need to ship fast:
+
+1. Branch from `main` (or the production tag, if you have one).
+2. Name: `hotfix/<short-description>` or `hotfix/<incident-id>`.
+3. Make ONE change. Atomic commit. No "while I'm here" piggybacks.
+4. PR to `main` (and to release branch if you have one) — fast review, fast merge, fast deploy.
+5. Verify in production.
+6. Add a regression test on `main` if hotfix didn't include one.
+
+Hotfix discipline matters because the temptation is to bundle other fixes — and hotfix bundles cause the next outage.
+
+## Stacked branches (advanced)
+
+Sometimes you must stack branches: feature B depends on feature A, A is in review.
+
+Options:
+
+1. **Wait for A to merge.** Best, when possible. Start B from updated `main`.
+2. **Stack:** branch B from A. PR B against A. When A merges, rebase B onto `main`, update PR target.
+3. **Feature flag both A and B on `main`.** A merges first behind flag, B merges next behind flag, both flip on together.
+
+Option 3 is the cleanest at scale. Stacking causes review and rebase pain.
+
+## Anti-patterns
+
+- Branch named `bruno-changes` — meaningless.
+- Branch lives 3 weeks "because we're discussing the design" — branch isn't where design happens. Keep designing in docs/PRDs; branch when you're ready to code.
+- `git pull` instead of `git pull --rebase` on a personal feature branch — creates merge commits in your history that you'll then need to clean up.
+- Force-pushing to fix "a typo in the commit message" on a shared branch — use `git revert` + new commit instead.
+- Multiple developers on the same branch without coordinating push order — non-fast-forward errors and conflicts. Pick one driver per branch or coordinate.

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.