DevFoundry/.devfoundry/skills/process-retrospective.md

Skill: Process Retrospective

Purpose: Convert a completed spec's execution history into logged lessons, and escalate recurring friction into a concrete proposed change to a rule, skill, persona, or reference file. This is what makes the DevFoundry process self-improving instead of static.

Trigger: After the QA Verifier approves a spec (all acceptance criteria pass), before the spec is moved to specs/archive/.

Steps

1. Reconstruct the spec's history. Read the spec in specs/active/SPEC-<id>-<short-name>.md, its Implementation Plan task list, and the Verification & Regression Plan checklist.
2. Ask the deviation question. Did Builder (Legacy Specialist / Modern Builder) deviate from any rule in .devfoundry/rules/, or did QA catch something a rule should have prevented? If yes, note what rule was missing or insufficient.
3. Ask the reference-gap question. Did anyone have to look up or guess environment details, schema facts, or dialect quirks that .devfoundry/references/* should already document? If yes, draft the missing fact as a direct edit.
4. Ask the requirements question. Did the spec-interview (.devfoundry/skills/spec-interview.md) miss a question that caused rework after implementation started? If yes, note the missing interview question.
5. Ask the repetition question. Did regression-check verification repeat the same manual steps this spec has needed before? If yes, note it as a candidate to fold into .devfoundry/skills/regression-check.md as a standing check.
6. Write the log entry. Append to .devfoundry/improvement-log.md using the format below. Always append — never rewrite prior entries.
7. Check for recurrence. If this entry's Category is none (no friction occurred), do not add it to the Friction Tally — the tally tracks recurring problems, not clean runs, and a clean run must never trigger the escalation below. Otherwise, update the “Friction Tally” table at the top of .devfoundry/improvement-log.md for this entry's Category + affected file (increment Count, append this spec's ID). If the updated Count is 3 or more:
   • Draft the specific edit to the affected .devfoundry/rules/, .devfoundry/skills/, .devfoundry/personas/, or .devfoundry/references/ file.
   • Present the diff to the user for approval before applying it (per the Process Improver's behavioral rules).
   • Mark the log entry ESCALATED and record what was changed once approved.
8. Do not block on this. Log and (if warranted) propose, but let the QA-approved spec proceed to archive regardless of whether an improvement is applied.

Log Entry Format

## <YYYY-MM-DD> — SPEC-<id>
- **What worked:** <brief>
- **Friction:** <brief, or "none">
- **Category:** rule-gap | reference-gap | interview-gap | repeated-verification | none
- **Affected file:** <the .devfoundry/rules|skills|personas|references file this friction relates to, or "none">
- **Proposed change:** <file + summary, or "none">
- **Status:** LOGGED | ESCALATED | APPLIED