@kennethsolomon/shipkit 3.6.0 → 3.8.0

package/README.md

@@ -93,21 +93,15 @@ Brainstorm → Plan → Branch → [Schema] → Write Tests → Implement → Co
 | 10 | `/sk:execute-plan` | TDD green: make tests pass |
 | 11 | `/sk:smart-commit` | Conventional commit |
 | 12 | **`/sk:lint`** | **GATE** — Lint + Dep Audit — all linters must pass |
-| 13 | `/sk:smart-commit` | Auto-skip if already clean |
-| 14 | **`/sk:test`** | **GATE** — 100% coverage on new code |
-| 15 | `/sk:smart-commit` | Auto-skip if already clean |
-| 16 | **`/sk:security-check`** | **GATE** — 0 issues |
-| 17 | `/sk:smart-commit` | Auto-skip if already clean |
-| 18 | **`/sk:perf`** | **GATE** *(optional)* — critical/high findings = 0 |
-| 19 | `/sk:smart-commit` | Auto-skip if already clean |
-| 20 | **`/sk:review`** | **GATE** — Review + Simplify + Blast Radius — 0 issues including nitpicks |
-| 21 | `/sk:smart-commit` | Auto-skip if already clean |
-| 22 | **`/sk:e2e`** | **GATE** — E2E Tests — prefers Playwright CLI when config detected, falls back to agent-browser; all scenarios must pass |
-| 23 | `/sk:smart-commit` | Auto-skip if already clean |
-| 24 | `/sk:update-task` | Mark done, log completion |
-| 25 | `/sk:finish-feature` | Changelog + PR |
-| 26 | `/sk:features` | Sync Features — update docs/features/ specs *(required)* |
-| 27 | `/sk:release` | Version bump + tag *(optional)* |
+| 13 | **`/sk:test`** | **GATE** — 100% coverage on new code |
+| 14 | **`/sk:security-check`** | **GATE** — 0 issues |
+| 15 | **`/sk:perf`** | **GATE** *(optional)* — critical/high findings = 0 |
+| 16 | **`/sk:review`** | **GATE** — Review + Simplify + Blast Radius — 0 issues including nitpicks |
+| 17 | **`/sk:e2e`** | **GATE** — E2E Tests — prefers Playwright CLI when config detected, falls back to agent-browser; all scenarios must pass |
+| 18 | `/sk:update-task` | Mark done, log completion |
+| 19 | `/sk:finish-feature` | Changelog + PR |
+| 20 | `/sk:features` | Sync Features — update docs/features/ specs *(required)* |
+| 21 | `/sk:release` | Version bump + tag *(optional)* |
 
 > **Fix & Retest Protocol:** All code-producing gates (Lint, Test, Security, Performance, Review, E2E) apply the Fix & Retest Protocol: logic changes require updating unit tests before committing the fix. Fix immediately, then re-run — never ask the user to re-run.
 
@@ -183,6 +177,7 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/sk:plan` | Create or refresh task planning files |
 | `/sk:setup-claude` | Bootstrap project scaffolding (CLAUDE.md + tasks/) |
 | `/sk:setup-optimizer` | Enrich CLAUDE.md by scanning the codebase |
+| `/sk:reverse-doc` | Generate architecture/design docs from existing code |
 
 ### Development
 
@@ -195,6 +190,7 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/sk:change` | Handle a mid-workflow requirement change — assess scope and re-enter at the right step |
 | `/sk:debug` | Structured bug investigation: reproduce → isolate → fix |
 | `/sk:hotfix` | Emergency fix workflow — skips design and TDD |
+| `/sk:fast-track` | Abbreviated workflow for small changes — skip planning, keep all gates |
 
 ### Prototyping
 
@@ -212,6 +208,8 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/sk:perf` | Performance audit: bundle size, N+1 queries, Core Web Vitals |
 | `/sk:seo-audit` | SEO audit — dual-mode (source templates + dev server), ask-before-fix, checklist output to `tasks/seo-findings.md` |
 | `/sk:review` | Blast-radius-aware self-review across 7 dimensions + cross-file impact analysis |
+| `/sk:gates` | Run all quality gates in optimized parallel batches |
+| `/sk:scope-check` | Compare implementation against plan, detect scope creep |
 
 ### Shipping
 
@@ -222,6 +220,7 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/sk:finish-feature` | Write changelog entry + create PR |
 | `/sk:release` | Version bump + CHANGELOG + git tag + push |
 | `/sk:features` | Sync docs/features/ specs with the codebase |
+| `/sk:retro` | Post-ship retrospective: velocity, blockers, action items |
 
 ### Laravel
 

package/commands/sk/security-check.md

@@ -12,7 +12,15 @@ By default, this checks only files changed on the current branch. Use `--all` to
 
 ## Hard Rules
 
-- **DO NOT fix code.** This is an audit — report only. The user decides what to fix.
+- **Fix all in-scope findings** (files in `git diff main..HEAD --name-only`) immediately after the audit. auto-commit with `fix(security): resolve [severity] security findings`. Re-run the audit until 0 findings remain.
+- **Pre-existing findings** (files outside the current branch diff): log to `tasks/tech-debt.md` using this format — do NOT fix inline:
+  ```
+  ### [YYYY-MM-DD] Found during: sk:security-check
+  File: path/to/file.ext:line
+  Issue: description of the vulnerability
+  Severity: critical | high | medium | low
+  ```
+- **Gates own their commits** — the fix-commit-rerun loop is fully internal. No manual commit step needed after this gate.
 - **DO NOT skip checks** because the project is small or simple. Production is production.
 - **Every finding must cite a specific file and line number.**
 - **Every finding must reference the standard it violates** (OWASP, CWE, NIST, etc.).
@@ -165,13 +173,11 @@ Tell the user:
 > "Security audit complete. Findings saved to `tasks/security-findings.md`.
 > - **Critical:** N open (N resolved) | **High:** N open (N resolved) | **Medium:** N open | **Low:** N open
 >
-> Review the findings, then run `/sk:finish-feature` when ready to finalize."
+> All in-scope findings have been fixed and committed. Pre-existing issues logged to `tasks/tech-debt.md`."
 
 If there are Critical or High findings:
 > "There are critical/high findings that MUST be fixed before merging. These are HARD GATE items — `- [ ]` findings block all forward progress. Fix them, then re-run `/sk:security-check` to verify."
 
-**Do not auto-fix.** The user decides what to address.
-
 ### Fix & Retest Protocol
 
 When applying a fix, classify it before committing:

package/commands/sk/update-task.md

@@ -16,6 +16,15 @@ Mark the current task as complete and log progress.
 - In `tasks/todo.md`, change the task's checkbox from `[ ]` to `[x]`
 - If the task has subtasks, verify all subtasks are also checked
 
+### 2.5. Mark Resolved Tech Debt
+
+- Read `tasks/tech-debt.md` if it exists
+- Find any unresolved entries (entries with no `Resolved:` line) whose `File:` or `Issue:` description relates to files or features changed in the current task (cross-reference with `tasks/todo.md` plan and current branch diff via `git diff main..HEAD --name-only`)
+- For each matched entry, append this line directly after the entry's `Severity:` line:
+  `Resolved: [YYYY-MM-DD] — [current branch name]`
+- Never delete entries — only append the `Resolved:` line
+- If `tasks/tech-debt.md` doesn't exist or no matches found: skip silently
+
 ### 3. Log Completion
 - Append a completion entry to `tasks/progress.md`:
 

package/commands/sk/write-plan.md

@@ -19,6 +19,11 @@ Create a decision-complete plan **before** writing code.
      constraints, and open questions explicitly into the plan
    - `tasks/lessons.md` — if it exists, apply all active lessons as constraints
      before writing any plan steps
+   - `tasks/tech-debt.md` — if it exists, filter to entries with no `Resolved:` line (unresolved only).
+     If any unresolved items exist, after presenting the draft plan ask:
+     > "There are N unresolved tech debt items in `tasks/tech-debt.md`. Should any be included in this task?"
+     List the unresolved items (file, issue, severity). If the user says yes, add them as tasks in the plan before final approval.
+     If the file doesn't exist or has 0 unresolved entries, skip silently.
 3. Update `tasks/todo.md` with:
    - **Goal** (1–2 lines)
    - **Milestones** — group tasks under milestone headers for multi-phase projects

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennethsolomon/shipkit",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "description": "A structured workflow toolkit for Claude Code.",
   "keywords": [
     "claude",

package/skills/sk:context/SKILL.md

@@ -32,6 +32,7 @@ Load all project context files into the conversation and output a formatted sess
 | 5 | `tasks/lessons.md` | All active lessons — read in full, apply as constraints for this session |
 | 6 | `docs/decisions.md` | If exists: last 3 ADR entries. If missing: note "no decisions log yet" |
 | 7 | `docs/vision.md` | If exists: product name + value proposition. If missing: note "no vision.md found" |
+| 8 | `tasks/tech-debt.md` | If exists: count entries with no `Resolved:` line (unresolved), highest severity among unresolved |
 
 ### Reading Strategy
 
@@ -58,6 +59,7 @@ Last done:  [last progress.md entry summary, 1 line]
 Pending:    [N] checkboxes remaining in todo.md
 Lessons:    [count] active — [most critical 1-liner from lessons.md]
 Open Qs:    [open questions from findings.md, or "none"]
+Tech Debt:  [N] unresolved — highest: [severity] ([file:line])
 Product:    [value prop from vision.md, or "no vision.md found"]
 ════════════════════════════════════════════
 ```
@@ -71,6 +73,7 @@ Product:    [value prop from vision.md, or "no vision.md found"]
 - **Pending:** Count `- [ ]` lines in `tasks/todo.md`. Stop counting at the first `## Verification`, `## Acceptance Criteria`, or `## Risks` heading (these are meta-sections, not tasks).
 - **Lessons:** Count `### [` headings in `tasks/lessons.md` (each lesson starts with `### [YYYY-MM-DD]`). Show the count + the **Prevention:** line from the most recent lesson.
 - **Open Qs:** Check for an "## Open Questions" section in `tasks/findings.md`. List them or say "none".
+- **Tech Debt:** Read `tasks/tech-debt.md` if it exists. Count entries that have no `Resolved:` line — each entry starts with `### [`. For unresolved entries, find the highest severity. Show `N unresolved — highest: [severity] ([file])`. If file missing or 0 unresolved, show `none`.
 - **Product:** From `docs/vision.md`, extract the value proposition. If file doesn't exist, say "no vision.md found".
 
 ---
@@ -96,6 +99,7 @@ After outputting the session brief:
 | No `tasks/lessons.md` | Show "0 active" for Lessons |
 | No `docs/decisions.md` | Show "no decisions log yet" — do not error |
 | No `docs/vision.md` | Show "no vision.md found" — do not error |
+| No `tasks/tech-debt.md` | Show "none" for Tech Debt field — do not error |
 | All checkboxes done in todo.md | Show "Task complete — 0 pending" |
 
 ---

package/skills/sk:e2e/SKILL.md

@@ -184,22 +184,39 @@ If any fail → apply Fix & Retest Protocol.
 
 When this gate requires a fix, classify it before committing:
 
-**a. Style/config/wording change** (CSS tweak, copy change, selector fix) → commit and re-run `/sk:e2e` (no unit test update needed)
+**a. Style/config/wording change** (CSS tweak, copy change, selector fix) → auto-commit with `fix(e2e): resolve failing E2E scenarios` and re-run `/sk:e2e`. Do not ask the user.
 
 **b. Logic change** (new branch, modified condition, new data path, query change, new function, API change) → trigger protocol:
 1. Update or add failing unit tests for the new behavior
 2. Re-run `/sk:test` — must pass at 100% coverage
-3. Commit (tests + fix together in one commit)
+3. Auto-commit tests + fix together with `fix(e2e): [description]`.
 4. Re-run `/sk:e2e` from scratch
 
 **Exception:** Formatter auto-fixes are never logic changes — bypass protocol automatically.
 
+Gates own their commits — the fix-commit-rerun loop is fully internal. No manual commit step needed after this gate.
+
 **This gate cannot be skipped.** All scenarios must pass before proceeding to `/sk:update-task`.
 
+### Pre-existing Issues
+
+If during E2E testing a bug is found in functionality **outside** the current feature being tested (pre-existing issue unrelated to this branch), do NOT fix it inline. Log it to `tasks/tech-debt.md`:
+
+```
+### [YYYY-MM-DD] Found during: sk:e2e
+File: path/to/file.ext:line
+Issue: description of the pre-existing bug
+Severity: critical | high | medium | low
+```
+
+Continue testing the current feature. Pre-existing bugs do not block this gate unless they affect the current feature's scenarios.
+
 ## Next Steps
 
 If all scenarios pass:
 > "E2E gate clean. Run `/sk:update-task` to mark the task done."
+>
+> No manual commit is needed — any fixes made during this gate were auto-committed.
 
 If failures remain after fixes:
 > "Re-running /sk:e2e — [N] scenarios still failing."

package/skills/sk:fast-track/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: sk:fast-track
+description: Abbreviated workflow for small, clear changes — skip planning ceremony, keep all quality gates
+user_invocable: true
+allowed_tools: Read, Write, Bash, Glob, Grep, Agent, Skill
+---
+
+# Fast-Track Flow
+
+Abbreviated workflow for small, well-understood changes. Skips brainstorm, design, plan, and write-tests phases but still enforces all quality gates.
+
+## When to Use
+
+- Config changes, dependency bumps, copy/wording changes
+- Small refactors with obvious scope
+- Adding a missing test for existing code
+- Fixing a typo or updating documentation
+- Any change where the "what" is already clear and doesn't need design exploration
+
+## When NOT to Use
+
+- New features (use full workflow)
+- Changes affecting multiple systems (use full workflow)
+- Anything requiring design decisions (use `/sk:brainstorm` first)
+- Bug fixes (use `/sk:debug` flow)
+
+## Guard Rails
+
+Before proceeding, check the scope of planned changes:
+
+1. **Diff size check**: After implementation, run `git diff --stat HEAD`. If the diff exceeds **300 lines** changed:
+   > "This change is [N] lines — larger than the 300-line fast-track threshold. Consider the full workflow for better test coverage. Continue anyway? (y/n)"
+
+2. **New file count**: If more than **5 new files** are created:
+   > "You've created [N] new files. Consider running `/sk:write-tests` first. Continue anyway? (y/n)"
+
+3. **Migration check**: If any migration files are detected in changes, warn:
+   > "Migration files detected. Consider running `/sk:schema-migrate` for analysis."
+
+## Steps
+
+### 1. Context (quick)
+- Read `tasks/todo.md` — pick the task or accept user's description
+- Read `tasks/lessons.md` — apply active lessons as constraints
+
+### 2. Branch
+- Run `/sk:branch` to create a feature branch
+
+### 3. Implement
+- Write the code directly — no brainstorm, design, plan, or TDD phases
+- Focus on the minimal change needed
+
+### 4. Commit
+- Run `/sk:smart-commit` to stage and commit with conventional commit message
+
+### 5. Gates
+- Run `/sk:gates` — all quality gates in optimized parallel batches
+- This is the same gate process as the full workflow — no shortcuts on quality
+- Lint, test, security, perf, review, E2E all run
+
+### 6. Finalize
+- Run `/sk:finish-feature` for changelog + PR
+
+## Workflow Status
+
+Fast-track updates `tasks/workflow-status.md` with abbreviated steps:
+- Steps 1-2 (read): done
+- Steps 3-6 (explore, design, accessibility, plan): skipped (fast-track)
+- Steps 7-11 (branch, implement, commit): done
+- Steps 12-17 (gates): handled by `/sk:gates`
+- Steps 18-21 (update, finalize, sync, release): done as applicable
+
+## Model Routing
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |

package/skills/sk:frontend-design/SKILL.md

@@ -111,13 +111,20 @@ Only run this phase if:
 - The user answers **y** or **yes** to the prompt above, OR
 - The user invoked the skill with `--pencil`
 
-### Step 1 — Find or create the .pen file
+### Step 1 — Derive the filename and open the .pen file
 
-Check `docs/design/` for an existing `.pen` file that matches this design (by name or topic).
+Before opening any Pencil document:
 
-- **Existing file found**: call `open_document(filePath)` to open it, then skip to Step 3.
-- **No file found**: call `open_document('new')` to create a fresh canvas.
-  - The file will be saved to `docs/design/{design-name}.pen` — use a slug derived from the design subject (e.g., `docs/design/dashboard-analytics.pen`).
+1. Read `tasks/todo.md` and extract the task name from the first `# TODO` heading:
+   - Pattern: `# TODO — YYYY-MM-DD — <task-name>`
+   - Convert to kebab-case (e.g., `"Gate Auto-Commit + Tech Debt"` → `gate-auto-commit-tech-debt`)
+   - If no `# TODO` heading exists, derive a slug from the design subject instead (e.g., `dashboard-analytics`)
+
+2. Target path: `docs/design/[task-name].pen`
+
+3. Call `open_document('docs/design/[task-name].pen')` — use the full path whether the file exists or not. The tool auto-detects existence: opens the file if it's already there, creates it on disk if not.
+
+The `.pen` file is created at `docs/design/[task-name].pen` before any design work begins, ensuring the design is saved to disk and committable.
 
 ### Step 2 — Load design context
 

package/skills/sk:gates/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: sk:gates
+description: Run all quality gates in optimized parallel batches — one command instead of six
+user_invocable: true
+allowed_tools: Agent, Read, Write, Bash, Glob, Grep
+---
+
+# Gates Orchestrator
+
+Run all quality gates (lint, test, security, perf, review, e2e) in optimized batches. Replaces manually invoking 6 separate commands.
+
+## When to Use
+
+Run `/sk:gates` after committing implementation code (step 11). This single command handles steps 12-17 of the workflow.
+
+## Execution Strategy
+
+Gates are organized into 4 batches for maximum parallelism while respecting dependencies:
+
+### Batch 1 — Parallel Agents (lint + security + perf)
+
+Launch 3 agents simultaneously:
+
+1. **Linter agent** — runs all formatters, analyzers, dep audits
+2. **Security auditor agent** — OWASP audit on changed files
+3. **Performance auditor agent** — bundle, N+1, Core Web Vitals, memory
+
+These 3 have no dependencies on each other. Run them in parallel using the Agent tool.
+
+Wait for all 3 to complete. Collect results.
+
+### Batch 2 — Test Agent (sequential, needs lint fixes)
+
+After Batch 1 completes (lint may have auto-formatted code):
+
+4. **Test runner agent** — runs all test suites, ensures 100% coverage on new code
+
+### Batch 3 — Review (main context, needs test confirmation)
+
+After Batch 2 completes:
+
+5. **Review** — runs `/sk:review` in the main context (NOT as an agent) because review needs deep code understanding and access to the full conversation history
+
+### Batch 4 — E2E Agent (needs review fixes)
+
+After Batch 3 completes:
+
+6. **E2E tester agent** — runs full E2E verification
+
+## Gate Results
+
+After all 4 batches complete, output a summary:
+
+```
+=== Gate Results ===
+Lint:     clean (attempt N)
+Security: 0 findings (attempt N)
+Perf:     0 critical/high (attempt N)
+Tests:    X passed, 0 failed (attempt N)
+Review:   0 issues (attempt N)
+E2E:      Y scenarios passed (attempt N)
+
+All gates passed. Run /sk:update-task
+```
+
+## Failure Handling
+
+- Each agent handles its own fix → auto-commit → re-run loop internally
+- If any agent fails after 3 attempts → stop all gates and report to user
+- Do NOT proceed to the next batch if the current batch has unresolved failures
+- Update `tasks/workflow-status.md` for each gate as it completes:
+  - Steps 12-17 marked `done` with attempt count in Notes
+
+## 3-Strike Protocol
+
+If any single gate fails 3 times:
+1. Stop the entire gates process
+2. Log the failure to `tasks/progress.md`
+3. Report to user with details of what failed and what was tried
+4. Do NOT mark the step as done
+
+## Model Routing
+
+The orchestrator itself runs in the main context. Agents use their own model routing:
+- Linter: haiku (mechanical)
+- Test runner: sonnet
+- Security auditor: sonnet
+- Perf auditor: sonnet
+- E2E tester: sonnet
+- Review: main context model (opus or sonnet depending on profile)
+
+| Profile | Orchestrator Model |
+|---------|-------------------|
+| `full-sail` | opus (inherit) |
+| `quality` | opus (inherit) |
+| `balanced` | sonnet |
+| `budget` | sonnet |

package/skills/sk:lint/SKILL.md

@@ -91,11 +91,30 @@ Skip stacks not present in the project.
 ### 6. Fix and Re-run
 
 If any analyzer reports errors or the dep audit blocks:
-1. Fix all reported issues
+
+**Before fixing, classify each issue by scope:**
+
+- Run `git diff main..HEAD --name-only` to get the current branch diff.
+- If the issue is in a file **not** in that list (pre-existing issue outside the current branch), do **not** fix it inline. Log it to `tasks/tech-debt.md` in this format and move on:
+
+  ```
+  ### [YYYY-MM-DD] Found during: sk:lint
+  File: path/to/file.ext:line
+  Issue: description of the problem
+  Severity: high | medium | low
+  ```
+
+- If the issue is in a file **in** the branch diff (in-scope), fix it.
+
+**Fix loop (in-scope issues only):**
+1. Fix all in-scope issues
 2. Re-run formatters (fixes may need formatting)
 3. Re-launch all analyzers in parallel
 4. Re-run dep audit if any dependency was fixed
-5. Loop until every tool exits clean
+5. Auto-commit with message `fix(lint): resolve lint and dep audit issues` — do NOT ask the user
+6. Re-run from step 3 until every tool exits clean
+
+> Gates own their commits — the fix-commit-rerun loop is fully internal. No manual commit step needed after this gate.
 
 ### 7. Report Results
 
@@ -125,20 +144,22 @@ Only include lines for detected tools. All must show "clean" before this skill p
 
 When this gate requires a fix, classify it before committing:
 
-**a. Formatter auto-fix** (Pint, Prettier, gofmt, cargo fmt changed whitespace/style) → commit and re-run `/sk:lint`. Never a logic change — bypass protocol.
+**a. Formatter auto-fix** (Pint, Prettier, gofmt, cargo fmt changed whitespace/style) → auto-commit and re-run `/sk:lint`. Never a logic change — bypass protocol.
 
 **b. Analyzer fix** (PHPStan type error, Rector suggestion, ESLint error, ruff violation) → classify each fix:
-  - Type annotation, import order, unused var, style rule → **style fix** → commit and re-run
+  - Type annotation, import order, unused var, style rule → **style fix** → auto-commit and re-run
   - New guard clause, changed condition, extracted function, modified data flow → **logic change** → trigger protocol:
     1. Update or add failing unit tests for the new behavior
     2. Re-run `/sk:test` — must pass at 100% coverage
-    3. Commit (tests + fix together in one commit)
+    3. Auto-commit (tests + fix together in one commit)
     4. Re-run `/sk:lint` from scratch
 
 **c. Dependency vulnerability fix** (composer audit / npm audit finding) → classify:
-  - Version bump with no API change → **style fix** → commit and re-run
+  - Version bump with no API change → **style fix** → auto-commit and re-run
   - Version bump with API/behavior change → **logic change** → trigger protocol
 
+All commits in this protocol are automatic — do not prompt the user for commit approval.
+
 ---
 
 ## Model Routing

package/skills/sk:perf/SKILL.md

@@ -1,18 +1,27 @@
 ---
 name: sk:perf
-description: Performance audit. Use before /sk:review to catch performance issues: bundle size, N+1 queries, slow DB queries, Core Web Vitals, memory leaks, caching opportunities. Auto-detects stack. Reports findings — does NOT fix code.
+description: Performance audit. Use before /sk:review to catch performance issues: bundle size, N+1 queries, slow DB queries, Core Web Vitals, memory leaks, caching opportunities. Auto-detects stack. Fixes critical/high in-scope findings and auto-commits. Logs pre-existing issues to tech-debt.
 license: Complete terms in LICENSE.txt
 ---
 
 ## Purpose
 
-Audit the implementation for performance issues before the final review. This is an audit skill — it identifies issues and produces a findings report. It does NOT fix code.
+Audit the implementation for performance issues before the final review. This skill identifies issues, produces a findings report, fixes in-scope critical/high findings immediately, and auto-commits. Pre-existing findings outside the branch diff are logged to `tasks/tech-debt.md`.
 
 Run this skill after implementing and passing lint/tests, but before `/sk:review`.
 
 ## Hard Rules
 
-- **DO NOT fix code.** Report only. The user decides what to fix.
+- **Fix all critical and high in-scope findings** (files in `git diff main..HEAD --name-only`) immediately after the audit. Auto-commit with `fix(perf): resolve [severity] performance findings`. Re-run the audit until critical/high = 0.
+- **Medium/low in-scope findings:** fix them in the same commit if straightforward, otherwise log to `tasks/tech-debt.md`.
+- **Pre-existing findings** (files outside the current branch diff): log to `tasks/tech-debt.md` using this format — do NOT fix inline:
+  ```
+  ### [YYYY-MM-DD] Found during: sk:perf
+  File: path/to/file.ext:line
+  Issue: description of the performance issue
+  Severity: critical | high | medium | low
+  ```
+- **Gates own their commits** — the fix-commit-rerun loop is fully internal. No manual commit step needed after this gate.
 - **Every finding must cite a specific file and line number.**
 - **Every finding must include an estimated impact** (high/medium/low) and a recommendation.
 - **Auto-detect the stack** — only run checks relevant to what's present.
@@ -158,6 +167,8 @@ Write findings to `tasks/perf-findings.md`:
 
 **Never overwrite** `tasks/perf-findings.md` — append new audits with a date header.
 
+The report is written first, then fixes are applied to in-scope critical/high findings.
+
 ## When Done
 
 Tell the user:
@@ -165,7 +176,7 @@ Tell the user:
 > "Performance audit complete. Findings saved to `tasks/perf-findings.md`.
 > - **Critical:** N | **High:** N | **Medium:** N | **Low:** N
 >
-> Address critical and high findings, then run `/sk:review` to proceed."
+> All critical/high in-scope findings have been fixed and committed. Pre-existing issues logged to `tasks/tech-debt.md`. Run `/sk:review` to proceed."
 
 If there are no critical or high findings:
 > "No critical or high performance issues found. N medium/low findings noted in `tasks/perf-findings.md`. Run `/sk:review` to proceed."

package/skills/sk:retro/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: sk:retro
+description: Post-ship retrospective analyzing velocity, blockers, and patterns to generate actionable improvements
+user_invocable: true
+allowed_tools: Read, Glob, Grep, Bash, Write
+---
+
+# Retrospective
+
+Analyze completed work after shipping a feature to generate actionable insights for the next iteration.
+
+## When to Use
+
+Run `/sk:retro` after `/sk:finish-feature` or `/sk:release` to reflect on what went well, what didn't, and what to improve. Best run while context is fresh.
+
+## Steps
+
+### 1. Gather Data
+
+Read these files to build the retrospective:
+
+| File | What to Extract |
+|------|----------------|
+| `tasks/todo.md` | Planned tasks — count total, completed, dropped |
+| `tasks/progress.md` | Work log — errors, resolutions, session timestamps |
+| `tasks/workflow-status.md` | Step-by-step status — attempt counts, skip reasons |
+| `tasks/findings.md` | Design decisions — were they validated? |
+| `tasks/lessons.md` | New lessons added during this task |
+| `tasks/tech-debt.md` | Tech debt logged during gates |
+
+### 2. Analyze Git History
+
+```bash
+# Commits on this branch
+git log main..HEAD --oneline --format="%h %s"
+
+# Time span
+git log main..HEAD --format="%ai" | tail -1  # first commit
+git log main..HEAD --format="%ai" | head -1  # last commit
+
+# Files changed
+git diff main..HEAD --stat
+
+# Commit count
+git rev-list main..HEAD --count
+```
+
+### 3. Calculate Metrics
+
+| Metric | How |
+|--------|-----|
+| **Completion rate** | Completed tasks / Planned tasks * 100 |
+| **Velocity** | Commits per day, files changed per day |
+| **Gate performance** | Extract attempt counts from workflow-status.md Notes (e.g., "clean on attempt 3") |
+| **Blocker count** | Count "FAIL", "error", "blocked", "3-Strike" entries in tasks/progress.md |
+| **Rework rate** | Count fix commits (fix(lint):, fix(test):, etc.) vs feature commits |
+
+### 4. Identify Patterns
+
+- **Recurring blocker**: Same type of issue across multiple gates?
+- **Estimation accuracy**: Did planned scope match actual scope? (cross-ref with `/sk:scope-check` if available)
+- **Gate friction**: Which gates required the most fix cycles?
+- **Previous retro follow-up**: Read previous `tasks/retro-*.md` files — were action items addressed?
+
+### 5. Generate Action Items
+
+Produce 3-5 concrete, actionable improvements:
+- Each action item must have: **what** to do, **why** it matters, **when** to apply it
+- Prioritize systemic fixes over one-off patches
+- Flag recurring unaddressed items from previous retros as process concerns
+
+### 6. Write Report
+
+Save to `tasks/retro-YYYY-MM-DD.md`:
+
+```markdown
+# Retrospective — [date] — [task name]
+
+## Metrics
+| Metric | Value |
+|--------|-------|
+| Planned tasks | N |
+| Completed | X / N (Y%) |
+| Commits | Z |
+| Time span | A days |
+| Files changed | B (+C/-D) |
+| Gate attempts | lint: 1, test: 2, security: 1, ... |
+| Blockers | K |
+| Rework rate | R% |
+
+## What Went Well
+- [data-backed observation]
+
+## What Didn't Go Well
+- [data-backed observation, with blocker/error references]
+
+## Patterns
+- [recurring theme from this or previous retros]
+
+## Action Items
+1. **[What]** — [Why] — Apply during: [When]
+2. ...
+
+## Previous Action Item Follow-Up
+- [Action from last retro] — [Addressed / Still open]
+```
+
+### 7. Summary
+
+Output to user:
+```
+Retrospective saved to tasks/retro-YYYY-MM-DD.md
+Completion: X/N tasks (Y%)  |  Velocity: Z commits/day  |  Blockers: K
+Top action: [most important action item]
+```
+
+## Model Routing
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |