improve-dev-workflow

Improve the development workflow (the continuous-improvement loop)

The subject of this skill is the PROCESS, not the product. A project bug gets fixed in the project; this skill fires when the process that was supposed to prevent the bug did not: the authoring habits, the review agents, the hooks, the skills, the CLAUDE.md rules. Its output is upgraded harness artifacts plus a durable record, so the same failure class cannot recur silently.

The loop: Observe -> Diagnose -> Verify -> Learn -> Improve. Each step ends on a "Done when" line; do not start the next step before it holds.

Step 0: weigh it

Not every hiccup deserves the full loop.

• LIGHT (single incident, single artifact): one lesson, one obvious home. Do Observe and Diagnose inline, fix the one artifact directly, add the Verify step for that artifact only, and record (memory, or the project CLAUDE.md as a 1-instance candidate). No plan file needed, but step 5's rule applies here too: a check runs, or RULE-ONLY with its reason.
• FULL (repeated failures, cross-cutting, or the fix spans artifacts): the whole loop below, ending in a plan file + plan-gate before implementation.
• Promotion rule: the FIRST occurrence of a failure mode is a recorded candidate; the SECOND promotes it to a guardrail. Check the project CLAUDE.md and memory for prior instances before deciding the weight.

1. Observe: build the failure inventory

One numbered entry per incident, each with: the INCIDENT (what happened, verbatim evidence), the MECHANISM (why it happened, technically), and WHERE A GUARDRAIL COULD HAVE CAUGHT IT EARLIER. Rules:

• Read the session transcript FIRST: this session's own .jsonl, found the way save-context step 1 finds it, never the newest file on the machine. Default to the current session. After a compaction it is the only full record of what happened.

• Evidence is executed or measured, never remembered. Quote the failing output, the wrong count, the log line. "The suite stayed 28/28 when it should have read 30" is evidence; "the tests seemed not to run" is not.

• Include what WORKED too (the practices that caught the failures), because codifying a proven practice is as valuable as patching a gap.

• Keep incidents atomic: one mechanism per entry, so each maps to a specific guardrail.

• Then look through four lenses, one line each even when empty:

  • Navigation, when time went on finding a file, fact or dependency: a pointer in the running artifact.
  • Existing checks, before building any: list what already runs (CI, pre-commit, run_tests.py, hooks). One that is unwired or silently broken is the finding.
  • Tool economy, when a call cost many tokens or minutes: name the cheaper path.
  • Information access, when the answer sat in a log or service the session could not reach: the fix is a way to read it.