work-kit-cli 0.4.0 → 0.5.0

package/skills/wk-define/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: define
+description: "Run the Define phase — 2 steps that turn a vague idea into a concrete spec before Plan starts."
+user-invocable: false
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+You are the **Definition Lead**. Two focused steps turn the user's raw description into a tightened problem statement and a lightweight spec that the Plan phase can clarify against.
+
+## Steps (in order)
+
+1. **Refine** — Surface ambiguity in the request, propose 1–3 concrete framings, get the user to pick or correct one. Output: a tightened problem statement.
+2. **Spec** — Turn the tightened statement into a minimal PRD: goal, non-goals, users, success signal, constraints. Not architecture (that's Plan).
+
+## Execution
+
+For each step:
+1. Read the step file (e.g., `.claude/skills/wk-define/steps/refine.md`)
+2. Follow its instructions completely
+3. Write outputs to `.work-kit/state.md` under a section for that step
+4. Update `**Phase:** define` and `**Step:** <current>` in state.md
+5. Proceed to the next step
+
+## When this phase runs
+
+- **full-kit**: always (it's the first phase)
+- **auto-kit**: only for `feature` and `large-feature` classifications. Bug fixes, small changes, and refactors skip Define entirely — the user already knows what they want.
+
+## Recording
+
+Define is short, but you should still capture:
+
+- **`## Decisions`** — when you choose between framings, append: `**<context>**: chose <X> over <Y> — <why>`. The Decision capture in Refine is the most important — it locks in which interpretation the rest of the pipeline runs against.
+- **`## Observations`** — typed bullets under `[lesson|convention|risk|workflow]` if you notice something worth preserving.
+
+## Loop-back
+
+If **Spec** uncovers ambiguity that should have been caught in Refine:
+- Report outcome `revise` on Spec
+- The orchestrator loops back to Refine
+- Re-run Refine with the new ambiguity in mind
+- Then re-run Spec
+- Max 2 iterations
+
+## Final Output
+
+After both steps are done, append a `### Define: Final` section to state.md. This is what the Plan phase reads.
+
+```markdown
+### Define: Final
+
+**Verdict:** ready
+
+**Problem:** <tightened one-sentence problem statement from Refine>
+
+**Spec:**
+- **Goal:** <what success looks like, one sentence>
+- **Non-goals:** <bullets — what we are explicitly NOT doing>
+- **Users:** <who this is for>
+- **Success signal:** <how we know it worked — observable, ideally measurable>
+- **Constraints:** <bullets — hard limits, deadlines, dependencies>
+
+**Open Questions for Plan:**
+- <questions Define couldn't resolve, to be picked up in Plan/Clarify — empty if none>
+```
+
+Then:
+- Update state: `**Phase:** define (complete)`
+- Commit state: `git add .work-kit/ && git commit -m "work-kit: complete define"`
+
+## Boundaries
+
+### Always
+- Ask the user when the request has multiple plausible interpretations
+- Keep the spec to one screen — Define is *cheap*, not exhaustive
+- Cross every framing decision into `## Decisions` so wrap-up can graduate it to the knowledge layer
+- Stop when you've tightened the ask, NOT when you've designed it
+
+### Ask First
+- Choosing between framings (Refine must surface options to the user, not pick silently)
+- Adding non-goals the user did not mention (confirm before locking them out)
+
+### Never
+- Propose architecture, file paths, or implementation strategies — that is Plan's job
+- Investigate the codebase — Plan/Investigate handles that
+- Skip Refine because "the request is clear" — if it were, the user could have written the spec themselves
+- Inflate the spec to look thorough. Define exists to *narrow*, not to demonstrate effort

package/skills/wk-define/steps/refine.md

@@ -0,0 +1,71 @@
+---
+description: "Define step: Surface ambiguity in the request, propose framings, get user to pick one."
+---
+
+# Refine
+
+**Role:** Idea Refiner
+**Goal:** Take the user's raw description and turn it into a tightened, unambiguous problem statement. If the request is fuzzy, surface that — don't paper over it.
+
+## Instructions
+
+1. **Read the request** in `.work-kit/state.md` under `## Description`.
+
+2. **Identify ambiguities.** Look for:
+   - Vague nouns ("the system", "users", "better")
+   - Implicit assumptions ("obviously", "just", "simple")
+   - Missing actors (who triggers it? who benefits?)
+   - Missing scope (one screen? whole feature? whole product area?)
+   - Conflicting framings (could mean A or B and they lead to different builds)
+
+3. **Generate 1–3 framings.** A framing is a one-sentence interpretation of what the user *probably* means. If the request is genuinely clear, generate ONE framing and confirm it. If it's ambiguous, generate 2–3 distinct framings that lead to materially different builds.
+
+4. **Ask the user to pick** one framing or correct all of them. **You must wait for the answer.** Do not silently pick.
+
+5. **Write the tightened problem statement** based on the chosen framing. One sentence. Concrete nouns, named actors, observable outcome.
+
+## Output (append to state.md)
+
+```markdown
+### Define: Refine
+
+**Original Request:**
+<copy of the relevant lines from ## Description>
+
+**Ambiguities Found:**
+- <ambiguity 1 — what's vague and why it matters>
+- <ambiguity 2>
+- <... or "None — request is clear">
+
+**Framings Considered:**
+1. <framing A — one sentence>
+2. <framing B — one sentence>
+3. <framing C — one sentence — only if needed>
+
+**Chosen Framing:** <A | B | C> (confirmed by user)
+
+**Tightened Problem Statement:**
+<one concrete sentence — this is what Spec will work from>
+```
+
+Also append to `## Decisions`:
+
+```markdown
+- **Framing**: chose <A> over <B/C> — <why, in user's words if they explained>
+```
+
+## Rules
+
+- ONE step, ONE deliverable: a tightened problem statement.
+- You **must** ask the user to pick when there are multiple framings. Picking silently violates the "Ask, don't decide" principle.
+- Refine is allowed to be 5 minutes of work. If it takes longer, you're doing Plan's job.
+- Do NOT read code. Do NOT propose solutions. Do NOT design anything.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "The request is obvious — no need to ask" | If it were obvious, the user wouldn't need a Define phase. The whole point of Refine is to catch the assumption *you* are about to make. Surface it. |
+| "I'll pick the most likely framing and the user can correct me" | That wastes the next 6 steps if you guessed wrong. One question now saves an entire Plan phase. |
+| "Generating multiple framings feels artificial" | If you can only think of one framing, generate one and confirm it. The point is *finding* alternatives, not faking them. |
+| "I'll combine all framings into one comprehensive scope" | Combining framings produces a vague spec that means nothing. Pick one. The others go in non-goals if they came close. |

package/skills/wk-define/steps/spec.md

@@ -0,0 +1,70 @@
+---
+description: "Define step: Turn the tightened problem statement into a minimal PRD."
+---
+
+# Spec
+
+**Role:** Mini-PRD Author
+**Goal:** Convert the tightened problem statement from Refine into a minimal spec the Plan phase can clarify against. Five sections, no more.
+
+## Instructions
+
+1. **Read** `### Define: Refine` from `.work-kit/state.md`. The "Tightened Problem Statement" is your starting point.
+
+2. **Write the spec.** Five sections, each as short as possible while still being concrete:
+
+   - **Goal** — one sentence. What does success look like? Should be observable.
+   - **Non-goals** — bullets. What are we *explicitly not* doing? This is where you put framings that came close in Refine but lost.
+   - **Users** — who is this for? Be specific. "Users" is not specific. "Logged-in admins viewing the team settings page" is.
+   - **Success signal** — how do we know it worked? Ideally measurable. If you can't measure it, describe what an observer would see.
+   - **Constraints** — bullets. Hard limits: deadlines, dependencies, must-not-touch areas, budget, compatibility.
+
+3. **Audit your spec.** Read it back and ask:
+   - Is the Goal a single sentence? (If not, you have multiple goals — pick one or escalate.)
+   - Are non-goals concrete things, not platitudes? ("Not over-engineering" is not a non-goal.)
+   - Could you build the wrong thing if you only read this spec? If yes, sharpen it.
+   - Did Refine leave any ambiguity that resurfaced here? If so, report `revise` and loop back.
+
+4. **Decide outcome:**
+   - `done` — spec is solid, Plan can take it from here
+   - `revise` — Refine missed something, loop back
+
+## Output (append to state.md)
+
+```markdown
+### Define: Spec
+
+**Goal:** <one observable sentence>
+
+**Non-goals:**
+- <thing we are explicitly not doing>
+- <another thing we are explicitly not doing>
+
+**Users:** <specific actor in a specific context>
+
+**Success signal:** <what an observer would see, ideally measurable>
+
+**Constraints:**
+- <hard limit 1>
+- <hard limit 2>
+
+**Open Questions for Plan:**
+- <ambiguity that survived Define and should be picked up in Plan/Clarify — empty if none>
+```
+
+## Rules
+
+- Each section is **at most 3 lines**. If you can't fit it, you're designing, not specifying.
+- The spec is for the Plan phase, not the user. The user already approved the framing in Refine.
+- Do NOT propose architecture, file paths, libraries, or APIs. None of that.
+- Do NOT add acceptance criteria here — Plan/Clarify owns those.
+- If you find yourself needing more than 5 sections, you're building a PRD instead of a spec. Stop.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "I should add an Architecture section to be helpful" | Plan does architecture. Adding it here pollutes the boundary and means Plan re-litigates a decision Define wasn't equipped to make. |
+| "Non-goals feel like nitpicks, I'll skip them" | Non-goals are the most valuable section. They prevent scope creep in Build by stating up front what we're *not* doing. |
+| "The success signal is 'it works'" | "It works" is not a signal. If you can't describe what an observer would see, you don't know what success means yet — go back to Refine. |
+| "Constraints can be discovered during Plan" | Some can. The hard ones (deadlines, must-not-touch areas, regulatory) need to be locked in Define so Plan doesn't waste effort on impossible designs. |

package/skills/wk-plan/steps/architecture.md

@@ -51,3 +51,19 @@ description: "Plan step: Define technical design — data model, API surface, co
 - Include TypeScript types/interfaces that will be needed
 - If you need a migration, specify the exact columns and types
 - This is the technical contract — Blueprint will reference it directly
+
+## Recording Decisions
+
+When you choose between real alternatives in this step (a library, a data shape, a layering choice), append a bullet to `## Decisions` in state.md using **this exact shape**:
+
+```
+- **<context>**: chose <X> over <Y> — <one-sentence why>
+```
+
+Examples:
+```
+- **State store**: chose Zustand over Redux Toolkit — smaller surface, no boilerplate, project already uses it elsewhere.
+- **ID generation**: chose ULID over UUID v4 — sortable, K-ordered for index locality.
+```
+
+`work-kit extract` (run during `wrap-up/knowledge`) auto-graduates these into `.work-kit-knowledge/decisions.md` so the rationale survives the session. Bullets that don't match this shape are skipped silently — they stay scratch.

package/skills/wk-test/steps/browser.md

@@ -0,0 +1,92 @@
+---
+description: "Test step: Drive the running app via Chrome DevTools MCP and verify each user-facing acceptance criterion."
+---
+
+# Browser
+
+**Role:** Live Browser Verifier
+**Goal:** Exercise the running application through Chrome DevTools MCP and confirm each user-facing acceptance criterion behaves correctly in a real browser. The unit test suite (`verify`) and end-to-end suite (`e2e`) check what the developer wrote — `browser` checks what the user will actually see.
+
+## Driver: Chrome DevTools MCP
+
+This step uses the **Chrome DevTools MCP** server. There is no `*.spec.ts` file to write or maintain — you drive the browser interactively using MCP tools, the same way you use `Bash` or `Read`.
+
+If the MCP isn't available, `work-kit doctor` will have warned at session start. In that case:
+- Skip this step gracefully
+- Append `### Test: Browser` with `**Verdict:** skipped` and the reason
+- Continue to the next test step
+
+## When this step runs
+
+- **full-kit**: every UI session
+- **auto-kit**: `feature` and `large-feature` classifications, only when the request involves UI
+- **non-UI work**: skipped automatically by the workflow matrix
+
+The Test phase parallelizes `verify`, `e2e`, and `browser` — you run alongside them. If e2e is also enabled and they share a dev server, coordinate so you don't crash each other (see Rules below).
+
+## Instructions
+
+1. **Check the dev server.** Read project config (or `## Description` / `### Plan: Final`) to find how the dev server is started. If it isn't already running:
+   - Start it in the background
+   - Wait for it to be reachable (poll the health endpoint or root URL)
+   - Note the port
+
+2. **List the user-facing flows to verify.** Pull from `### Plan: UX Flow` if present, otherwise from the user-facing acceptance criteria in `## Criteria`. Each flow should be one observable user action with one observable outcome.
+
+3. **For each flow:**
+   - Use Chrome DevTools MCP to navigate to the relevant URL
+   - Perform the action (click, type, submit, etc.)
+   - Observe the result (text, element state, URL change, network response)
+   - Capture a screenshot to `.work-kit/test-browser/<flow-name>.png` for the record
+   - Capture any console errors or failed network requests
+
+4. **Record verdicts.** For each flow: `pass | fail | skip` with a one-sentence note.
+
+5. **Decide outcome:**
+   - `done` — all flows pass
+   - `needs_debug` — a flow fails in a way you can't immediately diagnose (the debug skill will help)
+   - `blocked` — dev server won't start, MCP unreachable, or environment broken
+
+## Output (append to state.md)
+
+```markdown
+### Test: Browser
+
+**Verdict:** pass | fail | skipped
+**Driver:** Chrome DevTools MCP
+**Dev Server:** <URL or "not started — skipped">
+
+**Flows:**
+- [pass|fail|skip] <flow name> — <one-sentence observation>
+- ...
+
+**Console Errors:** <count + brief or "None">
+**Failed Requests:** <count + brief or "None">
+**Screenshots:** .work-kit/test-browser/
+
+**Notes:**
+<anything the Validate step needs to know — or "None">
+```
+
+## Rules
+
+### Always
+- Verify against the **running app**, not against source files. The point of this step is catching things that pass unit tests but break in the browser.
+- Capture screenshots even for passing flows — they're cheap evidence and help future debugging.
+- Use the user-facing criteria as the source of truth for what to test, not the implementation.
+- Tear down anything you started (dev server, browser session) when you finish.
+
+### Never
+- Mock or stub the backend. If the backend is broken, that's a real failure — record it.
+- Skip flows because they're "obviously fine" without actually loading them.
+- Disable console error capture to avoid noise. Console errors are signal.
+- Run while another test step is hammering the same dev server endpoint — coordinate via the dev server lifecycle (start once, share, don't kill mid-run).
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "The unit tests passed, browser is just duplication" | Unit tests prove pieces work in isolation. Browser proves the assembly works for a real user. Unit-passing + browser-failing is the most common ship-broken pattern. |
+| "The console errors are unrelated to my change" | Then suppress them in code, not by ignoring them here. Unrelated console errors mean someone else's broken thing is hiding inside your safety net. |
+| "I'll skip the screenshots, they take time" | They take seconds. They're invaluable when something regresses three weeks from now and you want to know what the page looked like the day it shipped. |
+| "MCP isn't installed, I'll do the test manually" | Manual is fine for the user, not for this skill. If MCP is missing, mark `skipped` with the reason and let the user install it later. The pipeline must not stall on missing tooling. |

package/skills/wk-test/steps/e2e.md

@@ -1,23 +1,39 @@
 ---
-description: "Test step: Test user flows end-to-end."
+description: "Test step: Run the existing Playwright suite as a regression gate, and add specs only for genuinely new flows that nothing else covers."
 ---
 
 # E2E
 
-**Role:** End-to-End Tester
-**Goal:** Test the feature as a user would experience it.
+**Role:** Regression Gate + Selective Spec Author
+**Goal:** Keep the cumulative Playwright suite green, and add a new spec **only** when a user flow in this session isn't already covered by an existing test. `test/browser` handles live per-session verification via Chrome DevTools MCP — this step exists for **durable regression coverage**, not session-local checks.
 
 ## Instructions
 
 1. **Verify Playwright is installed.** Run `npx playwright --version`. If it fails or `@playwright/test` is missing from `package.json`, STOP and tell the user to run `work-kit setup` (which installs Playwright + Chromium and scaffolds a config).
-2. Review the UX Flow from the Plan phase.
-3. For each user flow defined:
-   - Write a Playwright test under the project's configured `testDir` (see `playwright.config.*`).
-   - Test the happy path.
-   - Test key edge cases (empty state, error state, boundary values).
-4. Run the tests with `npx playwright test`. All flows must pass before marking this step done.
-5. Capture screenshots at key states using Playwright's `page.screenshot()` or the `--trace on` flag.
-6. Focus on the most important flows — don't test every permutation.
+
+2. **Run the existing suite first.** `npx playwright test`. This is the regression gate — if anything the previous sessions wrote is now broken, you catch it here before touching anything new.
+   - All pre-existing tests must still pass.
+   - Regressions → fix the implementation (not the test), unless the test encodes a behavior that intentionally changed in this session. In that case, update the test *with a comment* explaining why.
+
+3. **Identify genuinely new flows.** Read `### Plan: UX Flow` and `## Criteria`. For each user flow in this session, ask:
+   - Does an existing spec under `testDir` already exercise this flow? (Grep for selectors, route paths, or the feature name.)
+   - If yes: **do not add a duplicate spec.** `test/browser` will cover the live verification; e2e's job here is done.
+   - If no: add **one** focused spec that covers the happy path + one or two critical edge cases. Not exhaustive permutations.
+
+4. **Re-run the suite** after any new spec is added. `npx playwright test`. Everything must be green.
+
+5. **Capture screenshots** only for new specs, via `page.screenshot()` or `--trace on`. Skip screenshots for existing specs — they're already in the regression record.
+
+## Spec Discipline (important)
+
+The suite is **cumulative** across sessions — every spec you add sticks around forever and becomes maintenance burden. Before adding any new spec:
+
+- **Prefer extending an existing spec** to adding a new file. If a relevant spec exists, add a `test(...)` block inside it rather than creating a sibling file.
+- **Write for the flow, not the feature.** A "user can log in" spec shouldn't be rewritten just because you added a new login method — extend it.
+- **No spec per session.** If the session made a small tweak to a flow that already has a spec, don't add a second spec for the tweak.
+- **Delete stale specs when you legitimately replace behavior** instead of leaving `.skip`'d husks.
+
+When in doubt: **don't write the spec.** `test/browser` will verify the feature works live; the next session that actually needs regression coverage for this flow can add it.
 
 ## Output (append to state.md)
 
@@ -25,32 +41,38 @@ description: "Test step: Test user flows end-to-end."
 ### Test: E2E
 
 **Verdict:** pass | fail
-**Tests Written:**
-- `<test file>`: <flow description>
+**Suite Result:** <X passing, Y failing> (pre-existing + any new)
+**Regressions Found:** <none | list of existing specs that broke + fixes applied>
+
+**New Specs Added:**
+- `<test file>`: <flow description — or "None — existing specs already cover this session's flows">
 
-**Flows Verified:**
-- <flow 1>: pass | fail (<details>)
-- <flow 2>: pass | fail (<details>)
+**New Specs Skipped (already covered):**
+- <flow> — covered by `<existing spec file>`
+- ... or "N/A"
 
-**Screenshots:**
+**Screenshots (new specs only):**
 - <description>: <path or "not applicable">
 
 **Notes:**
-- <edge cases tested, issues found>
+- <anything the Validate step needs to know>
 ```
 
 ## Rules
 
 - Playwright is the required E2E framework. Manual verification does NOT satisfy this step.
 - If Playwright is missing, halt and direct the user to `work-kit setup` — do not fall back to curl, manual steps, or another framework.
+- **Run the existing suite first**, always. A regression in pre-existing tests is more important than adding new coverage.
+- **No new spec unless coverage is genuinely missing.** Duplicate specs are a tax on every future session.
 - Focus on user-visible behavior, not internal implementation.
-- Screenshots are evidence — capture them for key states.
-- If a flow fails, fix the implementation (not the test) unless the test expectation is wrong.
+- If a flow fails, fix the implementation (not the test) unless the test encodes a behavior that intentionally changed this session.
 
 ## Anti-Rationalization
 
 | Excuse | Reality |
 |--------|---------|
-| "Manual verification counts as E2E testing" | It does not. The E2E step requires automated Playwright tests. If Playwright is unavailable, halt and ask the user to run `work-kit setup`. |
-| "Unit tests already cover this flow" | Unit tests mock boundaries. E2E tests verify the real flow across boundaries — database, API, UI. A function can pass its unit test and still fail in the real pipeline. |
-| "E2E tests are slow and fragile, not worth the effort" | Slow tests that catch real bugs are more valuable than fast tests that miss them. Write focused E2E tests for critical paths, not exhaustive ones for every edge case. |
+| "Every session should add its own spec for documentation" | No. Specs are executable safety nets, not docs. An unneeded spec adds flakiness and maintenance with zero regression value over the spec that already covers the flow. |
+| "I'll add a spec just in case — it can't hurt" | It can. Each spec adds suite runtime, a selector that can rot, and a merge-conflict surface. "Just in case" accumulates until the suite is 20 minutes long and half-skipped. |
+| "Manual verification counts as E2E testing" | It does not. This step either runs Playwright green or halts. Live verification is `test/browser`'s job, not a fallback for e2e. |
+| "Unit tests already cover this flow" | Unit tests mock boundaries. E2E tests verify the real flow across database, API, and UI. Keep the e2e spec if no unit+integration combination could catch a boundary regression. |
+| "The existing spec is close enough, I'll write a new one anyway" | Extend the existing spec with a new `test(...)` block instead. Two specs for nearly the same flow is worse than one spec that covers both cases. |

package/skills/wk-wrap-up/SKILL.md

@@ -26,7 +26,7 @@ The summary you write goes into `.work-kit/summary.md`; the CLI archives it into
 4. **Run** `work-kit complete wrap-up/summary --outcome done`
 
 ### Step 2: knowledge
-5. **Run `work-kit extract`** — mechanically routes Observations / Decisions / Deviations / loopbacks into `.work-kit-knowledge/` files
+5. **Run `work-kit extract`** — routes typed `## Observations` bullets and tracker loopbacks/skipped/failed steps into `.work-kit-knowledge/` files. `## Decisions` and `## Deviations` are not auto-harvested (they're scratch space).
 6. **Review the summary you just wrote** for subjective additions the parser would miss. For each, call `work-kit learn --type <lesson|convention|risk|workflow> --text "..."`.
 7. **Run** `work-kit complete wrap-up/knowledge --outcome done`
 

package/skills/wk-wrap-up/steps/knowledge.md

@@ -14,13 +14,16 @@ After `wrap-up/summary`. By now you've just re-read the full `state.md` and dist
    ```bash
    work-kit extract
    ```
-   This parses `.work-kit/state.md` and `.work-kit/tracker.json` and routes entries to `.work-kit-knowledge/{lessons,conventions,risks,workflow}.md`. It pulls from:
-   - `## Observations` typed bullets (`- [lesson|convention|risk|workflow] text`)
-   - `## Decisions` → conventions
-   - `## Deviations` → workflow feedback
+   This parses `.work-kit/state.md` and `.work-kit/tracker.json` and routes entries to `.work-kit-knowledge/{lessons,conventions,risks,workflow,decisions}.md`. It pulls from:
+   - `## Observations` typed bullets (`- [lesson|convention|risk|workflow|decision] text`) — auto-harvested
+   - `## Decisions` bullets matching `**<context>**: chose X over Y — <why>` — auto-harvested into `decisions.md`
    - `tracker.json.loopbacks[]` → workflow feedback
    - Skipped/failed steps → workflow feedback
 
+   `## Deviations` is **not** auto-harvested — it's agent scratch space (test plans, review notes). If something in there is worth preserving, restate it as a typed bullet under `## Observations` (or call `work-kit learn` directly in step 2).
+
+   Free-form bullets under `## Decisions` (lines that don't match `**context**: chose X over Y`) are skipped silently — they're treated as scratch.
+
    The output JSON tells you how many entries were `written` vs `duplicates`. Re-running is idempotent.
 
 2. **Read your `.work-kit/summary.md`** (the one you just wrote). For each non-obvious thing in it that the parser would NOT have captured automatically, call `work-kit learn`:
@@ -29,6 +32,7 @@ After `wrap-up/summary`. By now you've just re-read the full `state.md` and dist
    work-kit learn --type lesson --text "Discovered that the test fixtures must be reset between Playwright suites, otherwise auth state leaks."
    work-kit learn --type risk --text "src/payment/webhook.ts has no integration test coverage for retries."
    work-kit learn --type convention --text "All new API endpoints must register a Zod schema in src/schemas/."
+   work-kit learn --type decision --text "**Browser driver**: chose Chrome DevTools MCP over Playwright — agentic, no spec files to maintain."
    work-kit learn --type workflow --text "The wk-test/e2e step doesn't tell agents to start the dev server before running Playwright."
    ```
 
@@ -46,6 +50,7 @@ After `wrap-up/summary`. By now you've just re-read the full `state.md` and dist
 | `lesson` | lessons.md | Project-specific learnings — facts about *this* codebase. |
 | `convention` | conventions.md | Codified rules this project follows. Future sessions should respect these. |
 | `risk` | risks.md | Fragile or dangerous areas. Touch with care. |
+| `decision` | decisions.md | Architectural choices: what was picked, what was rejected, why. Read before re-litigating. Auto-harvested from `## Decisions` when bullets follow the `**context**: chose X over Y — <why>` format. |
 | `workflow` | workflow.md | Feedback about the work-kit kit itself — skill quality, step skips, loopbacks, failure modes. **Mined manually across projects to improve work-kit upstream.** |
 
 ## Boundaries