--- name: sdlc description: Full SDLC workflow for implementing features, fixing bugs, refactoring code, testing, releasing, publishing, and deploying. Use this skill when implementing, fixing, refactoring, testing, adding features, building new code, or releasing/publishing/deploying. argument-hint: "[task description]" --- # SDLC Skill - Full Development Workflow

## Skill source & precedence

Loaded from repo-local **`.claude/skills/sdlc/SKILL.md`**, which wins over global `~/.claude/skills/` — the project's authoritative contract. Global is for cross-repo tooling only. Unsure which is active? `head -5` both.

## Task $ARGUMENTS

Operational checklist — **complete on its own**. Full protocol (optional depth, Claude Code installs only): `CLAUDE_CODE_SDLC_WIZARD.md`; if absent, do not hunt for it.

**If the user requests /sdlc, ALWAYS run the full workflow — even for mechanical tasks.** Never silently skip; if overkill, say so and ask.

## Full SDLC Checklist

Your FIRST action must be a task list covering every phase below — `TodoWrite`, or `TaskCreate` where that is what your harness exposes. Compact form (omit `activeForm` to use the subject as the spinner label):

``` TodoWrite([ // PLANNING { content: "Find and read relevant documentation", status: "in_progress" }, { content: "Assess doc health - flag issues (ask before cleaning)", status: "pending" }, { content: "DRY scan: What patterns exist to reuse? New pattern = get approval", status: "pending" }, { content: "Prove It Gate: adding new component? Research alternatives, prove quality with tests", status: "pending" }, { content: "Blast radius: What depends on code I'm changing?", status: "pending" }, { content: "Design system check (if UI change)", status: "pending" }, { content: "Scope card BEFORE work: one issue, acceptance criteria, allowed paths, exclusions, risk tier, estimated diff", status: "pending" }, { content: "Scrutinize test design - right things tested? Follow TESTING.md?", status: "pending" }, { content: "Present approach + STATE CONFIDENCE LEVEL", status: "pending" }, { content: "Signal ready - user exits plan mode", status: "pending" }, // TRANSITION { content: "Doc sync: update or create feature doc — MUST be current before commit", status: "pending" }, // IMPLEMENTATION { content: "TDD RED: failing test FIRST where a RED mutation is writable — watch EACH assertion fail; otherwise three-way call (see TDD proves)", status: "pending" }, { content: "TDD GREEN: Implement, verify test passes", status: "pending" }, { content: "Adding a guard? Name the requested behavior or field it binds to — if none, DO NOT ADD IT, file it (#617)", status: "pending" }, { content: "Run lint/typecheck", status: "pending" }, { content: "Run ALL tests", status: "pending" }, { content: "Production build check", status: "pending" }, // REVIEW { content: "DRY check: Is logic duplicated elsewhere?", status: "pending" }, { content: "Visual consistency check (if UI change)", status: "pending" }, { content: "Security review (if warranted)", status: "pending" }, { content: "Cross-model review (high-stakes)", status: "pending" }, { content: "Scope guard: only changes related to task? No legacy/fallback code left?", status: "pending" }, // CI SHEPHERD { content: "Commit and push to remote", status: "pending" }, { content: "Watch CI - fix failures, iterate until green (max 2x)", status: "pending" }, { content: "Read CI review - implement valid suggestions, iterate until clean", status: "pending" }, { content: "Meta-repo only: run local shepherd if PR needs E2E score (optional)", status: "pending" }, { content: "Post-deploy verification (if deploy task)", status: "pending" }, // FINAL { content: "Present summary: changes, tests, CI status", status: "pending" }, { content: "Capture learnings (TESTING.md, CLAUDE.md, or feature docs)", status: "pending" }, { content: "Close out plan files: mark complete or delete", status: "pending" } ]) ```

## SDLC Quality Checklist (Scoring Rubric)

| Criterion | Points | Critical? | What Counts | |-----------|--------|-----------|-------------| | task_tracking | 1 | | Use TodoWrite or TaskCreate | | confidence | 1 | | State HIGH/MEDIUM/LOW | | tdd_red | 2 | **YES** | Write/edit test files BEFORE implementation files, where a RED mutation is writable (see TDD proves) | | plan_mode_outline | 1 | | Outline steps before coding | | plan_mode_tool | 1 | | Use TodoWrite/TaskCreate/EnterPlanMode | | tdd_green_ran | 1 | | Run tests, show runner output | | tdd_green_pass | 1 | | All tests pass in final run | | self_review | 1 | | Read back files/diffs you modified | | clean_code | 1 | | One coherent approach, no dead code |

**Total: 10 points** (11 for UI tasks, +1 for design_system check). Critical miss on `tdd_red` = process failure regardless of total score — when a RED mutation was writable. Out-of-scope under the three-way call is not a miss.

## Test Failure Recovery

**ALL TESTS MUST PASS. NO EXCEPTIONS.** Test code is app code. Failures are bugs — investigate them like a 15-year SDET, not by brushing aside.

Not acceptable: "those were already failing", "not related to my changes", "it's flaky" (flaky = bug we haven't found yet).

When tests fail: 1. Identify which test(s) failed 2. Diagnose WHY: your code broke it (regression — fix code), test is for deleted code (delete test), test has wrong assertions (fix test), "flaky" (investigate — race, shared state, env) 3. Fix appropriately, run specific test individually first, then run ALL tests 4. Still failing after 2 attempts? Escalate (see Confidence Check) — not straight to the user

## Confidence Check (REQUIRED)

State your confidence before presenting an approach:

| Level | Meaning | Action | Effort | |-------|---------|--------|--------| | HIGH (90%+) | Know exactly what to do | Present, proceed after approval | Model default | | MEDIUM (60-89%) | Solid approach, some uncertainty | Present, highlight uncertainties | Model default | | LOW (<60%) | Not sure | Escalate, don't ask ↓ | **escalate now** (per model, see above) | | FAILED 2x | Something's wrong | Escalate, don't ask ↓ | **escalate now** | | CONFUSED | Can't diagnose | Escalate, don't ask ↓ | **escalate now** |

**Effort bumping is NOT optional** — bump BEFORE the next attempt.

**Confidence ramp:** Opus research → Fable batch review → 95% list → /goal TDD → Codex.

**Uncertainty ≠ a human question.** Use the model/tool evidence available before interrupting a human — escalate to Fable (`advisor()`; if down, a Fable subagent at `high`), then Codex `high`; reserve the user for priority/risk/scope/spend or irreversible calls. **Confidence is not authorization**: a high score never overrides approval, external-effect, production, release/merge or policy gates; merge protections are non-overridable. **Standing instructions stay in force** (wizard doc).

## Plan Mode

Use plan mode for: multi-file changes, new features, LOW confidence, bug investigation. **Skip plan approval step** (auto-approval) when confidence HIGH (95%+) AND single-file/trivial AND no new patterns AND no architectural decisions — still announce approach, don't wait. When in doubt, wait.

## Long-Running Goals (`/goal`)

Native `/goal <condition>` (**v2.1.143+**). Haiku evaluator re-checks transcript per turn. **NEVER invoke below HIGH 95%** — below that it rubber-stamps flailing as progress. **Condition MUST name the DLC** (`/sdlc` etc.) so the evaluator anchors on "doing it right." **Pre-flight:** trusted workspace; `disableAllHooks`/`allowManagedHooksOnly` off. **Condition = contract:** end state + check + constraints + hard bound; e.g. `/goal "tests pass + clean tree following /sdlc, stop after 20 turns"`. Evaluator can't call tools; `--resume` resets counters.

## Recommended Model

**Recommended: Opus 5 `high`** for complex projects, `medium` for routine web/CRUD; escalate `xhigh` only for genuinely hard runs. **Sonnet 5 `medium`** for simple work. Pin `claude-opus-4-8` for a same-family escape. **Effort is model-aware, not blanket `max`** — set via `/effort` per session, never a shell-rc env var (overrides post-switch). `/model` persists; picker `s` does not.

**Autocompact: set neither override by default.** For a deliberately earlier boundary use `CLAUDE_CODE_AUTO_COMPACT_WINDOW` alone — a smaller window compacts sooner, and nothing in that range switches compaction off. On **current Opus** a percentage alone is inert unless the window is also set, and then the two multiply; on Sonnet 5 and on a 200K Opus 4.6 pin it is live, so size it against THAT window (#520). **Advisor (v2.1.170+):** `advisorModel: "fable"` works with all drivers above; set in `/claude-setup-wizard` Step 9.5.

## The Review Contract (give BOTH reviewers this, verbatim)

**Grade severity by impact if it shipped.** Not by how hard the fix is. Not by which round found it. Either one gets gamed to open or close a round.

| | | |---|---| | **P0** | Stop the world. Prod broken, data loss, secret leaked. Preempts the task. | | **P1** | This PR does not merge. It doesn't work, or it broke something that did. | | **P2** | Real, should fix, ships fine without it. | | **P3** | Nit. |

**A finding blocks only if it is P0 or P1 and inside the scope card.** Fix a P2 or P3 here only if the diff is small and you already touched the file. Otherwise file it.

**Also answer: is this the right way to build it?** Should this code exist? Is it proportionate? Return **SOUND**, **CONCERN** (ship it, here's the debt), or **WRONG SHAPE** (stop, redesign). No severity level says "this should not exist", so nobody says it. *(#539: four rounds, seven real P1s, guard deleted at the end. WRONG SHAPE ends that at round 1.)*

**File anything outside the scope card as a GitHub issue. Never build it here.** This binds reviewers too: an out-of-card finding gets reported and filed, and does not block certification. *(#520: 20 rounds, 46 lines, nothing to compare growth against.)*

**Do not certify a doc that instructs commands unless the output is pasted.** The other leg can check this, which is the point. Reading catches judgement defects; only running catches wrong commands. *(#572: both legs certified a doc whose update command fails outright.)*

**Review against the issue's acceptance criteria, verbatim.** A stricter bar you invented in your own prompt is self-inflicted scope. *(#553: two rounds on a bar #530 never contained.)*

Ship good code, not perfect code. No glaring issues, right shape. Otherwise you never ship.

## Cross-Model Review (REQUIRED for High-Stakes)

**When to run:** high-stakes changes (auth, payments, data), releases/publishes, complex refactors. **Skip (log justification):** trivial, hotfixes, risk < review cost. **Reviewer:** `gpt-5.6-sol` `high` — adversarial diversity. **Cadence:** Fable during design, Codex once per frozen scope; don't stack both unless the decision needs two independent reviewers.

**Fable decides, Codex checks.** Fable rules on design, priority and sequencing *before* you commit to an approach — not a reviewer of work already done. A second repair to the same component in one cycle is a design question for Fable, not a third patch: review converges on a fix, never on the right design.

**No test costs more rounds than the change it guards.** When a guard accretes rounds past its own change, delete the guard and file the follow-up — the rounds are being spent on the needle, not the risk. #476 spent six on twenty doc lines: four bought real defects, two bought spellings of `sudo`, and the guard was deleted at round six anyway (#551).

PROTOCOL is universal across domains; only `review_instructions` and `verification_checklist` change.

**Handoff/preflight mechanics: wizard doc.** These two stay; improvising them cost real time (#364, #437).

1. **FALSIFY YOUR OWN WORK FIRST — the reviewer is not your test phase.** Before launching a leg, make a checklist with o