@brunosps00/dev-workflow 0.9.0 → 0.11.0

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.

package/scaffold/skills/dw-debug-protocol/references/non-reproducible-strategy.md

@@ -0,0 +1,108 @@
+# Non-reproducible bugs — strategy when you can't trigger it on demand
+
+Some bugs only fire in production, only for some users, only some times. The protocol differs from normal debugging because step 1 (reproduce) is the open question. Don't fix what you haven't seen.
+
+## Don't fix on guess
+
+The strongest urge with a non-reproducible bug is: "I bet I know what it is — let me push a fix and see if reports stop." This fails because:
+
+1. If the fix doesn't work, you wasted a deploy and learned nothing about the cause.
+2. If reports stop (correlation), you can't tell whether your fix worked or the trigger condition stopped occurring.
+3. You build a habit of guessing; the next bug, you guess wrong.
+
+Instead: instrument first, fix second.
+
+## The four sub-strategies
+
+### A. Timing / race conditions
+
+**Signs:** "Fails 1 out of N runs," "Worked locally, fails in CI," "Started failing after we sped up X."
+
+**Strategy:**
+1. Add timing-stamped logs at every async boundary in the suspect path.
+2. Push to a branch with extra logging; run the suite multiple times in CI.
+3. Compare the timestamps of failure runs vs success runs. Look for: events arriving in different order, gaps that exceed expectations.
+4. Once you see the order anomaly, you have the reproduction (forced via test that constrains order).
+
+**Tools:**
+- `Date.now()` or `performance.now()` in logs.
+- For network: response time logging.
+- For tests: `--repeat 100` (Jest, Vitest) to amplify rare failures.
+- Chaos: insert random `await sleep(rand)` at suspected boundaries to provoke order issues.
+
+### B. Environment-specific
+
+**Signs:** "Works in dev, fails in staging," "Works for one user, fails for another," "Worked yesterday, fails today, no code changes."
+
+**Strategy:**
+1. Diff the environments. Run a script that prints config (env vars, dependencies, OS, locale, feature flags) in both.
+2. Bisect by environment delta: change one variable at a time in the failing environment toward the working environment. The change that flips the bug is the cause.
+3. If user-specific: capture the user's state (account flags, history, A/B variants, browser, region) — diff against a working user.
+
+**Tools:**
+- Per-user replay: instrument enough that you can re-run a single user's session.
+- A/B comparison: working vs failing pair.
+- Feature flag audit: every flag that differs is a suspect.
+
+### C. State-dependent
+
+**Signs:** "Happens to long-time users, never new ones," "Only after they've done X then Y," "Cache-related," "Database-state-related."
+
+**Strategy:**
+1. Identify the state precondition. (Usually the failing user has a value or pattern in their data that the test fixtures don't.)
+2. Capture the failing user's state (sanitized DB rows, sanitized client state).
+3. Reproduce locally by seeding that exact state. Now you have a deterministic reproduction.
+4. Once reproduced, run the standard six-step protocol.
+
+**Tools:**
+- DB dump / sanitize / load locally.
+- Client state export (localStorage, IndexedDB, in-memory store snapshot).
+- Replay system that takes a captured state and replays user actions.
+
+**Privacy:** Sanitize before capturing. Production user data should never sit in dev environments unsanitized.
+
+### D. Frequency-dependent (rare)
+
+**Signs:** "We see this once a week," "Maybe 0.1% of requests," "Customer complained but logs don't show it."
+
+**Strategy:**
+1. Add specific logging or telemetry that would catch the bug NEXT time it fires.
+2. Deploy the logging.
+3. Wait for next occurrence (set up an alert if possible).
+4. Use the captured event as your reproduction.
+
+**Tools:**
+- Structured logs filterable by error pattern.
+- Sentry / Bugsnag / similar with breadcrumbs (action history before failure).
+- Custom telemetry on the suspect code path.
+
+**Time discipline:**
+- Don't sit waiting forever. Set a deadline ("if no event in 7 days, escalate or reprioritize").
+- Continue other work in parallel; this bug is "instrumented and waiting," not "actively in progress."
+
+## When to ship a guess
+
+Sometimes the bug is high-impact and waiting for instrumentation isn't acceptable. In that case:
+
+1. Acknowledge it's a guess in the commit and PR. Don't pretend you reproduced it.
+2. Make the fix MINIMAL. Don't rewrite a module to fix an unconfirmed bug — you'll cause new bugs.
+3. Add monitoring/alerting that would catch the bug if it persists. The fix has a verification path: "no recurrence reports in N days."
+4. Plan a follow-up: if the bug returns, fall back to the instrument-first protocol.
+
+A guess fix shipped with explicit acknowledgement is acceptable. A guess fix shipped pretending it was a real diagnosis is not — that pattern erodes the team's trust in fix quality.
+
+## Anti-patterns
+
+- "Just add a try/catch and log it" → hides the bug; report stops; cause persists.
+- "Restart the service / clear the cache" — operational mitigation, not a fix. Document it as such.
+- Fix shipped without monitoring → no way to know if it worked.
+- Fix shipped touching unrelated code → "while I was in there" expansion that turns one unverified change into many.
+- Refusing to ship until reproduced when production is suffering — perfectionism that costs users. Use the "ship a minimal guess" path with clear acknowledgement.
+
+## When to escalate
+
+After 4 hours instrumenting + waiting with no reproduction:
+
+- Surface the situation: what's instrumented, what's expected, what window of time you're waiting.
+- Ask whether to (a) keep waiting, (b) ship a minimal guess fix with monitoring, (c) reprioritize.
+- The decision is the user/team's, not yours alone. Provide the trade-off.

package/scaffold/skills/dw-debug-protocol/references/six-step-triage.md

@@ -0,0 +1,139 @@
+# Six-step debug triage
+
+Six discrete steps. Each has a specific output. Don't move to the next without finishing the current.
+
+## Step 1 — Reproduce
+
+**Question:** Can I trigger this on demand?
+
+**Output:** A failing test, a script, or a sequence of UI clicks that produces the bug. Save it. The reproduction IS the hypothesis test for your fix.
+
+**How:**
+- From a user report → ask: what version, what environment, what input, what was expected, what happened. Get all five before guessing.
+- From a stack trace → identify the entry point (HTTP route, CLI command, UI event) and the input that triggered it.
+- From a log line → find the surrounding context (request ID, user ID, timestamp); reconstruct the scenario.
+- Write a failing test FIRST when the bug is in pure logic. The test commits the bug to record before you fix it.
+
+**Common pitfall:** "It happens sometimes." This is not a reproduction. Either:
+- Find a deterministic trigger (often there's a state precondition you missed), OR
+- Quantify the rate (8/10 runs) and treat the test as flaky-but-progress.
+- See `non-reproducible-strategy.md` for state/timing/env-dependent cases.
+
+**Done when:** You have a one-line command (or a series of clicks) that produces the bug ≥80% of the time.
+
+## Step 2 — Localize
+
+**Question:** Where does the invariant break?
+
+**Output:** A file:line reference where state is wrong. Not where the symptom appears — where the cause lives.
+
+**How:**
+- Stack trace → walk UPWARDS from the failure point, asking at each frame: "is the input here valid?" The deepest frame with valid input is where the invariant breaks.
+- Bisect the change history if a recent commit broke things: `git bisect start && git bisect bad HEAD && git bisect good <known-good-sha>`.
+- Logs/instrumentation → add explicit log lines at suspected points; reproduce; narrow the window.
+- Debugger → set breakpoints at boundaries (entry/exit of suspect functions); inspect state.
+
+**Common pitfall:** Stopping at the first place that catches the error. The error often surfaces far from the cause.
+
+**Done when:** You can point at one specific function (or 2-3 closely related lines) and say "the violation happens here."
+
+## Step 3 — Reduce
+
+**Question:** What's the smallest input that triggers this?
+
+**Output:** A minimal reproduction — ideally 1-3 lines of input or a 5-10 line test case.
+
+**How:**
+- Start with your full reproduction.
+- Remove one element at a time (a config flag, a request field, a piece of state). Check if the bug still reproduces.
+- Repeat until removing anything else makes the bug disappear.
+
+**Why bother:**
+- Smaller repros are faster to test (your fix loop runs in seconds, not minutes).
+- Smaller repros surface the EXACT trigger; vague repros let you fool yourself.
+- The minimal repro often makes the cause obvious: "oh, it only fails when the array is empty."
+
+**Common pitfall:** Skipping this step because "I already know what's wrong." If you really know, the reduce takes 2 minutes. Do it.
+
+**Done when:** Removing one more thing makes the bug disappear.
+
+## Step 4 — Fix root cause
+
+**Question:** WHY is the invariant violated? Fix THAT.
+
+**Output:** Code change that addresses the cause, not the symptom.
+
+**How:**
+- Ask "why?" until you reach a design or assumption that's wrong, not just a bad value.
+  - "X is null" — why?
+  - "Because Y returned null" — why?
+  - "Because the cache was empty when called from this path" — why was the cache empty?
+  - "Because the warm-up runs after this path is reachable" — root cause: ordering.
+- Fix at the deepest "why" you can change without scope creep.
+- If the root cause is too deep ("this whole module assumes synchronous I/O"), fix at the shallowest level that makes the bug not recur, AND open a follow-up issue for the deeper fix.
+
+**Symptoms vs root cause — examples:**
+
+| Symptom fix (don't) | Root cause fix (do) |
+|---------------------|---------------------|
+| Catch the null and return default | Find why null was produced and prevent it |
+| Add a retry loop | Find why the first call failed |
+| Increase the timeout | Find why the operation is slow |
+| Add `if (process.env.NODE_ENV !== 'production')` guard | Find why prod has different behavior |
+| Suppress the warning | Address what the warning is warning about |
+
+**Common pitfall:** Adding `try/catch` around the symptom and moving on. This is hiding the bug, not fixing it.
+
+**Done when:** Reproduction now passes; lint + tests + build all green.
+
+## Step 5 — Guard against recurrence
+
+**Question:** What test would have caught this before deploy?
+
+**Output:** A regression test (or two) added to the suite that fails without your fix and passes with it.
+
+**How:**
+- Take the reproduction from step 1 → make it a test.
+- The test name should describe the bug ("returns empty list when cache warm-up is delayed", not "fix bug").
+- The test should fail clearly if the bug returns: assertion error with a message naming the invariant.
+- Place the test where future maintainers will find it (alongside the function with the cause, not in some catch-all "bugs.test.ts").
+
+**When you can't add a test:**
+- Bug requires production-only conditions: add a logging guard or a runtime invariant check that would fire on recurrence.
+- Bug is in infra/config: add a CI check that validates the config matches expectations.
+- Bug is in third-party library: open an upstream issue AND add a defensive wrapper with a test for your defense.
+
+**Common pitfall:** "I'll add the test later." You won't. Add it now or the bug returns.
+
+**Done when:** Test exists, was committed in same commit as fix, fails on `git revert <fix>`.
+
+## Step 6 — Verify end-to-end
+
+**Question:** Does the original report scenario now pass?
+
+**Output:** Proof — manual verification, screenshot, log trace, scripted E2E run.
+
+**How:**
+- Re-read the original bug report.
+- Run through it as if you're the reporter — same inputs, same path, same environment if possible.
+- Capture evidence (screenshot, terminal output, log line) that the issue no longer reproduces.
+
+**Why this step matters:**
+- Unit tests pass ≠ user-facing scenario works. The user's path may differ from the test's path.
+- Confirms you fixed the user's bug, not just A bug.
+- Catches "fixed it for case A but broke case B" regressions.
+
+**Common pitfall:** Stopping at "tests pass" and skipping the user-facing verification. Tests are necessary, not sufficient.
+
+**Done when:** You can confidently say "the original reporter would now see the expected behavior."
+
+## After all six steps
+
+The fix is ready to commit and ship:
+
+- Commit message: describes the bug, root cause, and fix in 1-3 sentences.
+- The regression test goes in the same commit as the fix.
+- If a deeper fix was deferred, the follow-up issue is linked from the commit.
+- E2E verification evidence is in the PR description (screenshot, log, run output).
+
+This is what "fixed" looks like. Anything less is "in progress."

package/scaffold/skills/dw-debug-protocol/references/stop-the-line.md

@@ -0,0 +1,52 @@
+# Stop the line — when to drop everything for a bug
+
+The Toyota factory metaphor: any worker can pull the cord and halt production when they see a defect. The reason isn't dramatic — it's economic. Defects compound downstream. Fixing one now is cheaper than ten later, on top of all the work that built on the broken state.
+
+In code, this means: when a real bug surfaces, you stop building features on top of unknown-state code.
+
+## What "stop the line" actually requires
+
+1. **Don't keep coding around it.** If a test is red, you don't merge other PRs that touch the same module until it's green.
+2. **Don't ignore "flaky" tests.** Flakiness is a bug — usually a race, sometimes a fixture. "Re-run the suite" is not a fix.
+3. **Don't downgrade priority without evidence.** "It's edge case" requires evidence the case is rare AND the impact is low. Often only one of those is true.
+4. **Document the pause.** A bug discovered → a tracking issue or task created → a clear "what's blocked by this" note.
+
+## When the rule bends
+
+Stop-the-line is not absolute. It bends when:
+
+- **The bug is in a parallel system you don't own.** Report it; continue your work. (Don't sit blocked waiting on someone else.)
+- **Production isn't on fire AND a release is shipping in <24h.** Sometimes "ship the working subset, fix the broken one in the next release" is correct. But this requires explicit acknowledgment, not silent slipping.
+- **The bug is informational, not blocking.** A console warning that doesn't affect behavior, a log noise, a deprecated-API notice — those go on a backlog, not stop the line.
+- **Reproduction needs production data.** Continue feature work in parallel branches; don't merge them until repro is achieved or scope-isolated.
+
+## When the rule does NOT bend
+
+- Tests are red and you don't know why → stop.
+- A previous green build went red after a merge → stop and bisect.
+- A user report can be reproduced → stop.
+- "Build passes locally but fails CI" → stop. CI is closer to truth.
+- Coverage drops below threshold without obvious reason → stop. (Removed a test silently?)
+
+## The cost of not stopping
+
+Three failure modes when teams ignore stop-the-line:
+
+1. **Compounding defects.** Bug A masks bug B; you fix A and now B surfaces in production. The user reports it as a regression of A's fix.
+2. **Lost reproduction.** A bug seen in commit N is hard to reproduce by commit N+5 because the surrounding code moved. The fix becomes "rewrite this whole area" because nobody can isolate the original issue anymore.
+3. **Test debt.** Red tests get marked `.skip` "temporarily" — and never come back. Three months later half the suite is skipped and nobody trusts it.
+
+## How to communicate "I'm stopping the line"
+
+- "Found a bug in X — pausing my current task to investigate. Will report status in 30 minutes."
+- "I can reproduce the issue. Estimated fix path: Y. Do you want me to push through, or hand off?"
+- "Stuck at localization for 60 minutes. Tried: A, B, C. Need fresh eyes."
+
+Brief, factual, no apology. Stopping is the right call; you're naming it.
+
+## Anti-patterns to avoid
+
+- "Quick fix and we'll come back to it" — almost never come back to it. Either fix root cause now or formally defer with a tracking issue.
+- "It might be flaky" — investigate, don't speculate. Flakiness has a cause.
+- Silently rolling back instead of investigating — you lost the chance to learn what broke.
+- "Worked around it" with a `// TODO: actual fix` — the workaround is now load-bearing in 3 weeks.

package/scaffold/skills/dw-git-discipline/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: dw-git-discipline
+description: Use when committing or opening a PR — applies trunk-based development, atomic commit discipline (one intent per commit, refactor separate from feature), conventional commit messages, and branch hygiene so history is bisectable and reviewable.
+---
+
+# Git Discipline
+
+> **Inspired by** [`addyosmani/agent-skills/git-workflow-and-versioning`](https://github.com/addyosmani/agent-skills/tree/main/git-workflow-and-versioning) (MIT). Trunk-based pattern, atomic commit principles, and branch-hygiene patterns adapted from Addy Osmani's work; specifics rewritten for dev-workflow's commit and PR commands.
+
+History is documentation. Bad commit hygiene corrupts the documentation; good hygiene makes future debugging cheap. This skill encodes the rules.
+
+## Three core principles
+
+### 1. One intent per commit
+
+A commit answers ONE question: "what did I change and why?" If your commit message has the word "and" connecting two unrelated changes — split it.
+
+Common splits:
+- Refactor + feature → two commits (refactor first, feature second).
+- Fix + style cleanup → two commits.
+- Type fix + behavior change → two commits.
+- Multiple bug fixes → one commit per bug.
+
+**Why this matters:** When something breaks 6 weeks later, `git bisect` returns the commit that introduced it. If that commit also did a rename, a refactor, and a feature, you've gained nothing. If it did one thing, you know what to revert.
+
+See `references/atomic-commits-discipline.md` for the discipline in detail.
+
+### 2. Trunk-based, short-lived branches
+
+Long-lived branches diverge from `main` and become merge nightmares. The discipline:
+
+- Branches live 1-3 days, max a week.
+- Daily merge or rebase from `main` to keep close to trunk.
+- Incomplete work behind feature flags, not behind a multi-week branch.
+- Small PRs (under ~400 lines diff). If bigger, ask: can this be split into independently-mergeable pieces?
+
+See `references/trunk-based-pattern.md` for when this bends and when it doesn't.
+
+### 3. Branch + commit message hygiene
+
+- **Branch names:** `feat/<scope>`, `fix/<scope>`, `refactor/<scope>`, `chore/<scope>`. Lowercase, kebab-case, ≤40 chars.
+- **Commit messages:** Conventional Commits (`type(scope): subject`) — `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `style`, `build`, `ci`, `perf`.
+- **Subject line:** ≤72 chars, imperative mood ("add" not "added"), no trailing period.
+- **Body (when needed):** explain WHY, not WHAT. The diff already shows what.
+- **Footer:** breaking-change marker, issue references, co-author lines.
+
+See `references/branch-hygiene.md` for naming conventions and rebase-vs-merge guidance.
+
+## What this skill enforces
+
+When wired into `/dw-commit`, every commit must:
+
+1. Have a single logical intent (one feature, one fix, one refactor — not mixed).
+2. Pass lint + tests + build BEFORE the commit is created.
+3. Use Conventional Commits format with correct type/scope.
+4. Have a body that explains WHY for non-trivial changes.
+5. NOT skip pre-commit hooks (`--no-verify` is forbidden unless user explicitly authorizes).
+6. NOT amend an already-pushed commit (history rewrites on shared branches break collaborators).
+
+When wired into `/dw-generate-pr`, every PR must:
+
+1. Have an explanatory description with summary + test plan, not just commit-list dump.
+2. Stay reasonably scoped (large PRs flagged with split suggestion).
+3. Have a branch that follows naming conventions.
+4. Reference an issue / PRD / spec when applicable.
+
+## Quick reference: when to do what
+
+| Situation | Action |
+|-----------|--------|
+| Mixed refactor + feature in working dir | Stage refactor → commit → stage feature → commit |
+| Pre-commit hook fails | Investigate. Fix root cause. NEVER `--no-verify` |
+| Want to "tidy up" before PR | `git rebase -i` BEFORE pushing — never after |
+| Already pushed and need to fix message | `git revert` + new commit. Don't force-push to shared. |
+| Branch is 5 days old, tons of conflicts | Rebase from main daily; don't let drift compound |
+| PR has 2,000 lines | Split. Identify natural seams: schema, backend, frontend, tests |
+| Stuck mid-merge with conflicts | Resolve, don't `git checkout --theirs` blindly. The conflict is information |
+
+## What this skill does NOT do
+
+- It does not push, force-push, or create branches without explicit user request.
+- It does not amend commits without explicit user request.
+- It does not collapse multiple commits via `git rebase -i` on already-pushed branches.
+- It does not enforce a specific commit count per PR — only that each commit is atomic.
+
+## Integration with dev-workflow commands
+
+- `/dw-commit` runs this skill — verifies lint/tests/build green, drafts a Conventional Commits message, splits commits if multi-intent detected.
+- `/dw-generate-pr` uses this skill to validate branch naming, PR body structure, and scope.
+- `/dw-run-task` and `/dw-run-plan` follow the atomic-commit discipline when their executor commits work — one task = one commit (or one logical sub-task).
+
+## Anti-patterns this skill prevents
+
+- "WIP" commits getting merged to `main` (pre-PR cleanup expected).
+- "Fix typo" follow-up commits that should have been amended in feature branch.
+- Commits with hooks bypassed (`--no-verify`) — root cause should be fixed instead.
+- Long-lived branches that drift from main.
+- PR descriptions that are just `git log` dumps.
+- Force-pushes to shared branches.
+- Commits that mix unrelated changes.
+
+## When discipline bends
+
+Real-world software can't always be perfect:
+
+- **Hotfix to production:** atomic still applies; hygiene bends only on subject-line conciseness if needed for clarity.
+- **Massive auto-generated change** (lockfile, codemod): one commit is fine; mark `chore(deps)` or `refactor(codemod)` clearly.
+- **Reverts:** use `git revert <sha>` (preserves history) over `git reset --hard` (rewrites history). Both create one commit; only revert is safe on shared branches.
+
+## Verification before committing
+
+- [ ] Lint passes
+- [ ] Tests pass
+- [ ] Build passes
+- [ ] One logical intent
+- [ ] Conventional Commits subject
+- [ ] Body explains WHY (when non-trivial)
+- [ ] No `--no-verify`
+- [ ] No amend of pushed commit
+- [ ] Branch name follows convention