@kennethsolomon/shipkit 3.19.0 → 3.20.0

package/skills/sk:lint/SKILL.md

@@ -30,97 +30,77 @@ Scan the project root for config files. Enable every matching stack:
 | `Cargo.toml` | Rust | `cargo fmt` | `cargo clippy` |
 
 Detection logic:
-- For `composer.json`: read `require-dev` keys for `laravel/pint`, `phpstan/phpstan`, `rector/rector`
-- For `package.json`: read `devDependencies` keys for `eslint`, `prettier`
-- For `pyproject.toml`: check `[tool.ruff]` section or `ruff` in `[project.optional-dependencies]` / `[build-system]`
-- For `go.mod` / `Cargo.toml`: presence of file is sufficient
+- `composer.json`: read `require-dev` keys for `laravel/pint`, `phpstan/phpstan`, `rector/rector`
+- `package.json`: read `devDependencies` keys for `eslint`, `prettier`
+- `pyproject.toml`: check `[tool.ruff]` section or `ruff` in `[project.optional-dependencies]` / `[build-system]`
+- `go.mod` / `Cargo.toml`: presence of file is sufficient
 
 Print detected stacks and tools before running anything.
 
 ### 3. Run Formatters — Sequential
 
-Formatters modify files, so run them one at a time in this order:
+Run in this order (formatters modify files — must not run in parallel):
 
-1. **Pint** (if detected): `vendor/bin/pint --dirty`
-2. **Prettier** (if detected): `npx prettier --write .`
-3. **ruff format** (if detected): `ruff format .`
-4. **gofmt** (if detected): `gofmt -w .`
-5. **cargo fmt** (if detected): `cargo fmt`
+1. Pint: `vendor/bin/pint --dirty`
+2. Prettier: `npx prettier --write .`
+3. ruff format: `ruff format .`
+4. gofmt: `gofmt -w .`
+5. cargo fmt: `cargo fmt`
 
-After each formatter, note which files changed. All formatters must finish before step 4.
+Note which files changed. All formatters must finish before step 4.
 
 ### 4. Run Analyzers — Parallel Sub-Agents
 
 Launch all detected analyzers in parallel using the Agent tool in a single message:
 
-- **PHPStan**: `vendor/bin/phpstan analyse --memory-limit=512M`
-- **Rector**: `vendor/bin/rector --dry-run`
-- **ESLint**: `npx eslint .`
-- **ruff check**: `ruff check .`
-- **golangci-lint**: `golangci-lint run`
-- **cargo clippy**: `cargo clippy`
+- PHPStan: `vendor/bin/phpstan analyse --memory-limit=512M`
+- Rector: `vendor/bin/rector --dry-run`
+- ESLint: `npx eslint .`
+- ruff check: `ruff check .`
+- golangci-lint: `golangci-lint run`
+- cargo clippy: `cargo clippy`
 
-Example with PHPStan + Rector + ESLint detected:
-```
-Agent 1: "Run vendor/bin/phpstan analyse --memory-limit=512M. Report all errors with file:line."
-Agent 2: "Run vendor/bin/rector --dry-run. Report all suggested changes with file:line."
-Agent 3: "Run npx eslint . Report all errors with file:line."
-```
+Each agent: "Run `<command>`. Report all errors/changes with file:line."
 
 ### 5. Run Dependency Audit
 
-Run dependency vulnerability checks for detected stacks:
-
 | Stack | Command | Block on |
 |-------|---------|----------|
-| PHP (composer.json) | `composer audit` | any severity with fix available (`composer audit` has no severity filter) |
+| PHP (composer.json) | `composer audit` | any severity with fix available |
 | Node (package.json) | `npm audit --audit-level=high` | high or critical |
 | Node (yarn.lock) | `yarn audit --level high` | high or critical |
 | Node (pnpm-lock.yaml) | `pnpm audit --audit-level high` | high or critical |
 | Python (pyproject.toml / requirements.txt) | `pip-audit` | high or critical |
 
-For each detected package manager, run the audit command and capture output.
-
-**Block (fail this gate):**
-- PHP: any vulnerability that has a fix available (`composer audit` exits non-zero for all severities — no filtering option exists)
-- Node/Python: critical or high severity vulnerabilities that have a fix available
-
-**Warn (pass with note):** medium/low severity for Node/Python, or any severity with no available fix — note in report but do not block.
+**Block (fail this gate):** PHP: any vuln with fix available (`composer audit` exits non-zero for all severities). Node/Python: critical or high with fix available.
 
-Skip stacks not present in the project.
+**Warn (pass with note):** medium/low for Node/Python, or any severity with no fix — log but do not block.
 
 ### 6. Fix and Re-run
 
-If any analyzer reports errors or the dep audit blocks:
+**Classify each issue before fixing:**
 
-**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:
+Run `git diff main..HEAD --name-only` to get branch diff.
 
+- **Out-of-scope** (file not in branch diff): do NOT fix inline. Log to `tasks/tech-debt.md`:
   ```
   ### [YYYY-MM-DD] Found during: sk:lint
   File: path/to/file.ext:line
   Issue: description of the problem
   Severity: high | medium | low
   ```
+- **In-scope** (file in branch diff): fix it.
 
-- If the issue is in a file **in** the branch diff (in-scope), fix it.
-
-**Fix loop (in-scope issues only):**
+**Fix loop (in-scope only):**
 1. Fix all in-scope issues
-2. Re-run formatters (fixes may need formatting)
+2. Re-run formatters
 3. Re-launch all analyzers in parallel
 4. Re-run dep audit if any dependency was fixed
-5. Re-run from step 3 until every tool exits clean
-6. Once all tools pass clean, make ONE squash commit: `fix(lint): resolve lint and dep audit issues` — do NOT ask the user
-
-> Squash gate commits — collect all fixes for the pass, then one commit. Do not commit after each individual fix.
+5. Repeat from step 3 until all tools exit clean
+6. Make ONE squash commit: `fix(lint): resolve lint and dep audit issues` — do NOT ask the user
 
 ### 7. Report Results
 
-Print one line per tool:
-
 ```
 Pint:          X files formatted / clean
 Prettier:      X files formatted / clean
@@ -143,23 +123,23 @@ Only include lines for detected tools. All must show "clean" before this skill p
 
 ## Fix & Retest Protocol
 
-When this gate requires a fix, classify it before committing:
+Classify every fix before committing:
 
-**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.
+**a. Formatter auto-fix** (Pint, Prettier, gofmt, cargo fmt changed whitespace/style) → auto-commit and re-run. 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** → 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. Auto-commit (tests + fix together in one commit)
-    4. Re-run `/sk:lint` from scratch
+**b. Analyzer fix** (PHPStan, Rector, ESLint, ruff) — classify:
+- 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** → protocol:
+  1. Update or add failing unit tests for the new behavior
+  2. Re-run `/sk:test` — must pass at 100% coverage
+  3. Auto-commit (tests + fix together)
+  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** → auto-commit and re-run
-  - Version bump with API/behavior change → **logic change** → trigger protocol
+**c. Dependency vulnerability fix** — classify:
+- Version bump, 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.
+All commits are automatic — do not prompt the user.
 
 ---
 

package/skills/sk:mvp/SKILL.md

@@ -21,60 +21,44 @@ Generate a complete, aesthetically polished MVP from a single idea prompt. Outpu
 
 ## Step 1 — Gather the Idea
 
-Ask the user to describe their product idea. If not already provided, ask:
+Ask: **"What's your product idea? Describe it in 1-3 sentences — what does it do and who is it for?"**
 
-> **What's your product idea? Describe it in 1-3 sentences — what does it do and who is it for?**
-
-Extract from their answer:
+Extract and confirm before proceeding:
 - **Product name** (or ask them to pick one)
 - **One-line value proposition**
 - **Target audience**
-- **Key features** (3-5 core features for the app)
-
-Confirm your understanding before proceeding.
+- **Key features** (3-5 core features)
 
 ---
 
 ## Step 2 — Pick a Tech Stack
 
-Present these preset options:
+Present options:
 
-> **Pick a tech stack:**
->
-> 1. **Next.js + Tailwind** — React ecosystem, SSR, API routes built-in
-> 2. **Nuxt + Tailwind** — Vue ecosystem, SSR, server routes built-in
-> 3. **Laravel + Blade + Tailwind** — PHP ecosystem, full backend, Blade templates
-> 4. **React + Vite + Tailwind** — Lightweight SPA, no backend (waitlist via Formspree)
->
-> Or type your own stack (I'll adapt).
+| # | Stack | Notes |
+|---|-------|-------|
+| 1 | **Next.js + Tailwind** | React, SSR, API routes built-in |
+| 2 | **Nuxt + Tailwind** | Vue, SSR, server routes built-in |
+| 3 | **Laravel + Blade + Tailwind** | PHP, full backend, Blade templates |
+| 4 | **React + Vite + Tailwind** | Lightweight SPA, no backend (waitlist via Formspree) |
 
-Once the user picks, note the selection and load the corresponding reference file in Step 6.
+Or accept a custom stack. Note the selection for Step 6.
 
 ---
 
 ## Step 3 — Optional Design Phase (Pencil MCP)
 
-Check if the user invoked with `--pencil` flag or ask:
-
-> **Would you like to design the UI visually in Pencil before coding? (Requires Pencil app + MCP) (y/n)**
->
-> If no, I'll go straight to code generation with a great default design.
+Check for `--pencil` flag or ask: **"Design UI visually in Pencil before coding? (y/n)"**
 
 ### If YES — Pencil MCP Design Phase
 
-Follow this flow (adapted from sk:frontend-design):
-
-**3a. Find or create .pen file**
-- Check `docs/design/` for existing `.pen` file matching this MVP.
-- Existing: `open_document(filePath)` → skip to 3c.
-- None: `open_document('new')` → save to `docs/design/{product-slug}.pen`.
+**3a.** Check `docs/design/` for existing `.pen` file. If found: `open_document(filePath)` → skip to 3c. If not: `open_document('new')` → save to `docs/design/{product-slug}.pen`.
 
-**3b. Load design context**
-1. `get_guidelines(topic='landing-page')` — load landing page design rules.
-2. `get_style_guide_tags` → `get_style_guide(tags)` — pick tags matching the product's tone (e.g., modern, SaaS, minimal, bold).
+**3b.** Load design context:
+1. `get_guidelines(topic='landing-page')`
+2. `get_style_guide_tags` → `get_style_guide(tags)` — pick tags matching product tone.
 
-**3c. Set color palette as variables**
-Decide a distinctive color palette based on the product's tone and audience. Call `set_variables` with the palette:
+**3c.** Set color palette via `set_variables`:
 ```json
 {
   "color-bg": "#xxxxxx",
@@ -84,29 +68,20 @@ Decide a distinctive color palette based on the product's tone and audience. Cal
 }
 ```
 
-**3d. Build mockup screens**
-Use `batch_design` to create:
-1. Landing page frame — hero, features, pricing, waitlist section
-2. App main screen frame — dashboard or primary view
-3. App secondary screen frame — detail view or key interaction
+**3d.** Use `batch_design` (one frame per call) to create:
+1. Landing page — hero, features, pricing, waitlist section
+2. App main screen — dashboard or primary view
+3. App secondary screen — detail view or key interaction
 
-Work one frame per `batch_design` call. Apply the color variables and typography.
+**3e.** After each frame: `get_screenshot` → if off, `snapshot_layout` → fix → iterate until correct.
 
-**3e. Validate and iterate**
-After each frame: `get_screenshot` to inspect. If off: `snapshot_layout` → fix with `batch_design`. Iterate until the design matches the vision.
+**3f.** Ask: **"Does this design direction look good? Any changes before I start coding?"** Wait for explicit approval before proceeding.
 
-**3f. Get user approval**
-Present screenshots and ask:
-> **Does this design direction look good? Any changes before I start coding?**
-
-Wait for approval. Apply feedback if given. Do not proceed to code without explicit approval.
-
-**3g. Record the design**
-Note the `.pen` file path. The design decisions (colors, typography, layout) carry forward into code generation.
+**3g.** Note the `.pen` file path. Design decisions (colors, typography, layout) carry forward into code.
 
 ### If NO — Skip to Step 4
 
-Use the aesthetic guidelines from `references/design-system.md` to make distinctive design choices automatically. Briefly state the design direction chosen (color scheme, typography, layout style) so the user knows what to expect.
+Use `references/design-system.md` for design choices. State the chosen direction (color scheme, typography, layout style) briefly.
 
 ---
 
@@ -118,124 +93,100 @@ Read the stack-specific reference file:
 - Laravel → `references/stacks/laravel.md`
 - React + Vite → `references/stacks/react-vite.md`
 
-Run the scaffold command from the reference file. Then customize the Tailwind config with the chosen color palette and typography.
+Run the scaffold command from the reference file. Customize Tailwind config with the chosen color palette and typography.
 
 ---
 
 ## Step 5 — Generate the Landing Page
 
-Read `references/landing-page.md` for section patterns and structure.
-
-Generate a complete landing page with these sections (all mandatory):
+Read `references/landing-page.md`. Generate all 9 mandatory sections:
 
-1. **Navbar** — logo/product name + nav links (Features, Pricing, Waitlist) + CTA button
-2. **Hero** — headline (benefit-driven) + subheadline + primary CTA + hero visual/illustration area
-3. **Social proof bar** — "Trusted by X+" or logo strip (use placeholder logos)
-4. **Features grid** — 3-6 feature cards with icons, titles, descriptions (based on the key features from Step 1)
-5. **How it works** — 3-step process with numbered steps and descriptions
-6. **Pricing** — 2-3 tier cards (Free / Pro / Enterprise) with fake but realistic pricing
-7. **Testimonials** — 2-3 fake testimonial cards with names, roles, photos (use placeholder avatars)
-8. **Waitlist / CTA section** — email input + submit button + success message + form validation
+1. **Navbar** — logo + nav links (Features, Pricing, Waitlist) + CTA button
+2. **Hero** — benefit-driven headline + subheadline + primary CTA + hero visual
+3. **Social proof bar** — "Trusted by X+" or logo strip (placeholders)
+4. **Features grid** — 3-6 cards with icons, titles, descriptions (from Step 1 features)
+5. **How it works** — 3-step numbered process
+6. **Pricing** — 2-3 tier cards (Free / Pro / Enterprise) with fake realistic pricing
+7. **Testimonials** — 2-3 fake cards with names, roles, placeholder avatars
+8. **Waitlist / CTA** — email input + submit + success message + validation
 9. **Footer** — product name, links, copyright
 
 ### Waitlist Email Collection
 
-**For stacks with backend (Next.js, Nuxt, Laravel):**
-- Create an API route that accepts POST `{ email }`.
-- Validate the email format server-side.
-- Read existing `waitlist.json`, append the new entry with timestamp, write back.
-- Return success/error JSON response.
-- Wire the landing page form to POST to this route via fetch.
-- Show success state ("You're on the list!") and error state on the form.
+**Stacks with backend (Next.js, Nuxt, Laravel):**
+- API route: POST `{ email }` → validate server-side → read `waitlist.json` → append `{ email, timestamp }` → write back → return JSON.
+- Wire form to POST via fetch. Show success ("You're on the list!") and error states.
 
-**For static stacks (React + Vite):**
-- Use Formspree: form action points to `https://formspree.io/f/{form_id}`.
-- Add a comment/note telling the user to create a free Formspree account and replace `{form_id}`.
-- Handle success/error states client-side.
+**Static stacks (React + Vite):**
+- Use Formspree: `action="https://formspree.io/f/{form_id}"`.
+- Add comment instructing user to create a free Formspree account and replace `{form_id}`.
+- Handle success/error client-side.
 
 ---
 
 ## Step 6 — Generate the App
 
-Generate a working multi-page app with:
+Generate a working multi-page app with these 5 pages:
 
-1. **Navigation** — sidebar or top nav with links to all pages. Active state highlighting.
-2. **Dashboard / Home** — summary cards, charts (use simple CSS/SVG charts or placeholder), recent activity list. All fake data.
-3. **Primary feature page** — the main thing the product does. Functional UI with fake data. Buttons, modals, forms all work (client-side only).
-4. **Secondary feature page** — a supporting feature. Table or list view with filtering/sorting (client-side).
-5. **Settings / Profile page** — simple form with fake prefilled data. Save button shows a toast/notification.
+1. **Navigation** — sidebar or top nav, links to all pages, active state highlighting.
+2. **Dashboard / Home** — summary cards, simple CSS/SVG charts, recent activity list (fake data).
+3. **Primary feature page** — main product function, functional UI, client-side only (buttons, modals, forms work).
+4. **Secondary feature page** — supporting feature, table/list with client-side filtering/sorting.
+5. **Settings / Profile** — form with fake prefilled data, save button shows toast.
 
-### Design Standards (apply to every page)
+### Design Standards (every page)
 
-Read `references/design-system.md` and apply:
-- Distinctive color palette — never default Tailwind. Custom `tailwind.config` colors.
-- Thoughtful typography — use Google Fonts. Pair a display font with a body font.
-- Consistent spacing scale — use a rhythm (e.g., 4/8/12/16/24/32/48).
-- Polished components — rounded corners, shadows, hover states, transitions.
-- Responsive — must look good on mobile and desktop.
-- Fake data should feel realistic — use real-sounding names, numbers, dates.
+Read `references/design-system.md`:
+- Custom Tailwind colors — never defaults.
+- Google Fonts — pair display + body font.
+- Consistent spacing rhythm (e.g., 4/8/12/16/24/32/48).
+- Rounded corners, shadows, hover states, transitions.
+- Responsive — mobile and desktop.
+- Fake data must feel realistic (real-sounding names, numbers, dates).
 
 ---
 
 ## Step 7 — Visual Validation (Playwright MCP)
 
-After code generation is complete, validate the output visually.
+**If Playwright MCP available:**
+1. Start dev server (stack's dev command from reference file).
+2. Navigate to each page: `/`, `/dashboard`, each app page.
+3. Screenshot at desktop (1280px) and mobile (375px).
+4. Check for: broken layouts, missing content, non-functional interactions, visual inconsistency.
+5. Fix issues and re-validate.
 
-**If Playwright MCP is available:**
-
-1. Start the dev server (use the stack's dev command from the reference file).
-2. Use Playwright MCP to navigate to each page:
-   - Landing page (`/`)
-   - Dashboard (`/dashboard`)
-   - Each app page
-3. Take screenshots of each page at desktop (1280px) and mobile (375px) widths.
-4. Check for:
-   - Broken layouts (overlapping elements, overflow, misaligned sections)
-   - Missing content (empty sections, broken images, placeholder text not filled)
-   - Non-functional interactions (click buttons, submit forms, open modals)
-   - Visual consistency (colors match palette, typography is consistent)
-5. If issues found: fix them and re-validate.
-
-**If Playwright MCP is NOT available:**
-
-Tell the user:
-> Playwright MCP is not connected — skipping visual validation. Start the dev server with `{dev command}` and check the pages manually.
+**If Playwright MCP NOT available:**
+Tell user: `"Playwright MCP not connected — start the dev server with {dev command} and check pages manually."`
 
 ---
 
 ## Step 8 — Quality Loop
 
-If visual validation found issues:
-
-1. Fix the identified issues.
-2. Re-run Playwright validation (Step 7).
-3. Repeat until all pages pass — no broken layouts, all interactions work, design is consistent.
-
-Maximum 3 loop iterations. If issues persist after 3 loops, present remaining issues to the user and ask how to proceed.
+1. Fix issues found in Step 7.
+2. Re-run Playwright validation.
+3. Repeat until all pages pass. Max 3 iterations — if issues persist, present remaining issues and ask how to proceed.
 
 ---
 
 ## Step 9 — Generate Project Context Docs
 
-Generate 3 lightweight documentation files in `docs/` from information already gathered in Steps 1-2. No new questions — use the product name, value prop, audience, features, and tech stack already captured.
-
-### Files to Generate
+Generate 3 files in `docs/` using information from Steps 1-2. No new questions.
 
 **`docs/vision.md`**
 ```markdown
 # [Product Name]
 
 ## Value Proposition
-[One-line value prop from Step 1]
+[One-line value prop]
 
 ## Target Audience
-[Target audience from Step 1]
+[Target audience]
 
 ## Key Features
-[Bullet list of 3-5 features from Step 1]
+[Bullet list of 3-5 features]
 
 ## North Star Metric
-[Suggest one metric that measures core value — e.g., "weekly active waitlist signups" or "daily feature usage"]
+[One metric measuring core value]
 ```
 
 **`docs/prd.md`**
@@ -243,13 +194,13 @@ Generate 3 lightweight documentation files in `docs/` from information already g
 # PRD — [Product Name]
 
 ## Overview
-[1-2 sentence product description]
+[1-2 sentence description]
 
 ## User Stories
-[For each key feature from Step 1, write a user story: "As a [audience], I want to [feature] so that [benefit]"]
+[Per key feature: "As a [audience], I want to [feature] so that [benefit]"]
 
 ## Feature Acceptance Criteria
-[For each feature, list 2-3 concrete acceptance criteria]
+[Per feature: 2-3 concrete criteria]
 
 ## Out of Scope (MVP)
 - Real authentication
@@ -263,19 +214,19 @@ Generate 3 lightweight documentation files in `docs/` from information already g
 # Tech Design — [Product Name]
 
 ## Stack
-- **Framework:** [chosen stack from Step 2]
+- **Framework:** [chosen stack]
 - **Styling:** Tailwind CSS
 - **Fonts:** [chosen fonts]
 
 ## Project Structure
-[List the key directories and files generated during scaffolding]
+[Key directories and files from scaffolding]
 
 ## Component Map
 ### Landing Page
-[List all 9 sections and their components]
+[All 9 sections and their components]
 
 ### App Pages
-[List each page and its key components]
+[Each page and its key components]
 
 ## Data Model
 ### Waitlist
@@ -283,19 +234,15 @@ Generate 3 lightweight documentation files in `docs/` from information already g
 - timestamp: ISO 8601 string
 
 ### Fake Data Entities
-[List the fake data structures used in the app]
+[Fake data structures used in the app]
 ```
 
-After generating the docs, output:
-> **Context docs generated:** `docs/vision.md`, `docs/prd.md`, `docs/tech-design.md`
-> These persist context for future sessions. Run `/sk:context` to load `docs/vision.md` into the session brief, or read the others directly.
+Output after generating: `"Context docs generated: docs/vision.md, docs/prd.md, docs/tech-design.md — Run /sk:context to load vision.md into the session brief."`
 
 ---
 
 ## Step 10 — Present the Output
 
-Summarize what was generated:
-
 ```
 ## MVP Generated
 

package/skills/sk:perf/SKILL.md

@@ -8,31 +8,28 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
 
 ## Purpose
 
-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`.
+Audit the implementation for performance issues before `/sk:review`. Produces a findings report, fixes in-scope critical/high findings, auto-commits. Pre-existing findings (outside branch diff) are logged to `tasks/tech-debt.md`.
 
 ## Hard Rules
 
-- **Fix all critical and high in-scope findings** (files in `git diff main..HEAD --name-only`) immediately after the audit. Re-run the audit until critical/high = 0. Once clean, make ONE squash commit: `fix(perf): resolve performance findings`.
-- **Medium/low in-scope findings:** fix them in the same pass 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:
+- Fix all critical and high in-scope findings (files in `git diff main..HEAD --name-only`). Re-run until critical/high = 0. ONE squash commit: `fix(perf): resolve performance findings`.
+- Medium/low in-scope: fix if straightforward, otherwise log to `tasks/tech-debt.md`.
+- Pre-existing findings (outside branch diff): log only — 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
   ```
-- **Squash gate commits** — collect all fixes for the pass, then one commit. Do not commit after each individual fix.
-- **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.
+- Squash gate commits — one commit per pass, not per fix.
+- Every finding must cite a specific file:line, estimated impact (high/medium/low), and a recommendation.
+- Auto-detect stack — only run checks relevant to what's present.
 
 ## Before You Start
 
-1. Detect the stack: read `CLAUDE.md`, check for `package.json`, `composer.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, etc.
-2. Determine scope: `git diff main..HEAD --name-only` to find changed files.
-3. If `tasks/perf-findings.md` exists, read it — check if prior findings have been addressed.
+1. Detect stack: read `CLAUDE.md`, check for `package.json`, `composer.json`, `go.mod`, `requirements.txt`, `Cargo.toml`.
+2. Determine scope: `git diff main..HEAD --name-only`.
+3. If `tasks/perf-findings.md` exists, read it — check if prior findings were addressed.
 4. If `tasks/lessons.md` exists, read it — apply performance-related lessons.
 
 ## Stack Detection
@@ -120,7 +117,7 @@ Run this skill after implementing and passing lint/tests, but before `/sk:review
 
 ## Generate Report
 
-Write findings to `tasks/perf-findings.md`:
+Write findings to `tasks/perf-findings.md` (never overwrite — append with date header):
 
 ```markdown
 # Performance Audit — YYYY-MM-DD
@@ -167,13 +164,11 @@ Write findings to `tasks/perf-findings.md`:
 | **Total** | **N** | **N**            |
 ```
 
-**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.
+Write the report first, then apply fixes.
 
 ## Fix Critical/High Findings via Agent
 
-If Critical or High findings exist, invoke the **`performance-optimizer` agent** to apply fixes:
+Invoke the **`performance-optimizer`** agent:
 
 ```
 Task: "Read tasks/perf-findings.md. Fix all Critical and High in-scope findings
@@ -181,43 +176,29 @@ Task: "Read tasks/perf-findings.md. Fix all Critical and High in-scope findings
 pass before AND after. Commit: fix(perf): resolve performance findings"
 ```
 
-The `performance-optimizer` agent works in worktree isolation and runs tests around every fix. After it completes, merge its worktree branch and verify the fix in `tasks/perf-findings.md`.
+Agent works in worktree isolation. After completion, merge its worktree branch and verify fixes in `tasks/perf-findings.md`.
 
-## When Done
+## Fix & Retest Protocol
 
-Tell the user:
+| Fix type | Action |
+|----------|--------|
+| Config/infrastructure (cache headers, compression, CDN config, pool size) | Commit → re-run `/sk:perf`. No test update needed. |
+| Logic change (N+1 fix, algorithm refactor, pagination, data structure) | 1) Update/add failing tests 2) `/sk:test` at 100% 3) Commit tests+fix together 4) Re-run `/sk:perf` |
+
+Logic changes include: N+1 fix (query count/data shape), algorithm change (output correctness), pagination (result set size). Tests must verify the optimized path produces correct results.
+
+## When Done
 
 > "Performance audit complete. Findings saved to `tasks/perf-findings.md`.
 > - **Critical:** N | **High:** N | **Medium:** N | **Low:** N
 >
 > 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:
+If no critical/high findings:
 > "No critical or high performance issues found. N medium/low findings noted in `tasks/perf-findings.md`. Run `/sk:review` to proceed."
 
 ---
 
-## Fix & Retest Protocol
-
-When applying a performance fix, classify it before committing:
-
-**a. Config/infrastructure change** (adding cache headers, enabling compression, changing CDN config, adjusting connection pool size) → commit and re-run `/sk:perf`. No test update needed.
-
-**b. Logic change** (fixing N+1 query by changing data-fetching logic, refactoring algorithm, modifying data structure, changing pagination logic) → trigger protocol:
-1. Update or add failing unit tests for the new optimized behavior
-2. Re-run `/sk:test` — must pass at 100% coverage
-3. Commit (tests + fix together in one commit)
-4. Re-run `/sk:perf` to verify the fix resolved the finding
-
-**Common logic-change performance fixes:**
-- N+1 fix: changes how related data is fetched → update tests that assert on query count or data shape
-- Algorithm change: O(n²) → O(n log n) → update tests that assert on output correctness
-- Pagination: adding LIMIT/offset → update tests that assert on result set size
-
-**Why:** Performance fixes often change how data is fetched or processed. Tests must verify the optimized path produces correct results.
-
----
-
 ## Model Routing
 
 Read `.shipkit/config.json` from the project root if it exists.