Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

sdd-distill-lessons

Distil per-spec retrospectives into specs/lessons.md so future spec authoring absorbs the learning. Reads specs/*/retrospective.md, groups recurring patterns, surfaces candidate lessons and tech-stack.md promotion candidates via AskUserQuestion, writes confirmed additions to specs/lessons.md, then invokes /review against the pending change before stopping.

jentic · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add jentic/jentic-api-scorecard --skill sdd-distill-lessons

About this skill


name: sdd-distill-lessons description: Distil per-spec retrospectives into specs/lessons.md so future spec authoring absorbs the learning. Reads specs/*/retrospective.md, groups recurring patterns, surfaces candidate lessons and tech-stack.md promotion candidates via AskUserQuestion, writes confirmed additions to specs/lessons.md, then invokes /review against the pending change before stopping. argument-hint: "(no arguments)" metadata: internal: true

/sdd-distill-lessons — distil retrospectives into specs/lessons.md

You are operating within a Spec-Driven Development (SDD) workflow. See .claude/rules/sdd-constitution.md.

This skill is the manual roll-up step of the SDD feedback loop. Per-spec specs/<date>-<slug>/retrospective.md files capture what individual specs missed; this skill reads them, deduplicates lessons across retrospectives, and writes the durable additions into specs/lessons.md so /sdd-new-spec and /sdd-new-phase consume them on their next run. When a lesson recurs across multiple retrospectives and clearly names a load-bearing invariant, the skill flags it as a specs/tech-stack.md promotion candidate for the user to hand-promote.

Hard constraints

  • specs/lessons.md only — no other writes. This skill edits exactly one file. specs/tech-stack.md promotions are surfaced as user-actionable suggestions; the skill never edits tech-stack.md. Retrospectives are read-only.
  • Do not write to disk before the AskUserQuestion confirmation completes. The grouped lesson candidates exist to lock in what gets captured; writing early wastes the call.
  • No git actions. This skill writes files and stops. Branching, committing, and PR creation are user actions per .claude/rules/git-workflow.md.
  • Ground every proposed lesson in at least one retrospective. Do not invent lessons; do not paraphrase a retrospective into a lesson it does not actually support.
  • Dedupe before proposing. If two retrospectives surface the same lesson (semantically), group them into one candidate referencing both retrospectives — do not propose duplicate bullets.
  • Do not re-propose already-captured lessons. Compare each candidate against the existing specs/lessons.md body and skip anything substantively present.

Phase 0 — Load context

Load in parallel:

  • @specs/mission.md
  • @specs/tech-stack.md
  • @specs/lessons.md
  • @.claude/rules/sdd-constitution.md

Enumerate specs/*/retrospective.md files (every dated feature-spec directory may or may not have one — retrospectives are optional). Load each in parallel via Read.

If no retrospectives exist, stop with a one-line summary ("No retrospectives found under specs/*/retrospective.md; nothing to distil.") — there is nothing to do.

Phase 1 — Parse retrospectives and existing lessons

For each retrospective, extract:

  • Phase number and title from the H1
  • Each bullet under ## Lesson for future specs
  • The ## Promotion candidate verdict (yes or no plus the rationale sentence)

For specs/lessons.md, extract the bullets currently present under ## Lessons (the section may still contain the initialisation placeholder _(empty — …)_ — treat that as no lessons captured yet).

Phase 2 — Group and dedupe candidate lessons

Combine all extracted lesson bullets from all retrospectives. Group lessons that say the same thing semantically (different phrasings of the same guidance count as one). For each grouped candidate:

  • Record the source retrospectives (one or more file paths)
  • Phrase the candidate as a single actionable bullet
  • Mark as a promotion candidate if either (a) two or more retrospectives surfaced this same lesson, or (b) any source retrospective marked ## Promotion candidate: yes. This surfacing threshold is intentionally looser than the constitution's promotion bar (which requires recurrence and invariant status) — better to surface a borderline candidate than miss one; the human applies the conjunction when deciding whether to actually hand-promote.

This full grouped set is the basis for promotion-candidate detection (Phase 5). From it, derive a new-candidate set by filtering out any lesson already substantively present in specs/lessons.md's existing bullet list. A lesson that is already captured can still qualify as a promotion candidate — being in lessons.md does not preclude promotion to specs/tech-stack.md.

If the new-candidate set is empty, skip Phases 3 and 4 (no AskUserQuestion, no file edit) and go directly to Phase 5 with a one-line note ("All retrospective lessons are already captured in specs/lessons.md; nothing new to add."). Phase 5 still runs to report any promotion candidates from the full grouped set.

Phase 3 — AskUserQuestion (MANDATORY, before any disk write)

Issue a single AskUserQuestion call (multi-select) listing the candidate lessons as options:

  • Prompt: "Which lessons should I add to specs/lessons.md?"
  • Header: Lessons (≤ 12 chars per the schema)
  • multiSelect: true
  • Per the schema, at most 4 options per call. If there are more than 4 candidates, present the 4 with the strongest signal first (highest source-retrospective count; ties broken by oldest retrospective first), and note in the response that remaining candidates can be reviewed on a follow-up run. Each option:
    • label: short version of the lesson (≤ ~40 chars; truncate with … if needed)
    • description: the full lesson bullet + (sources: <retro-1-path>[, <retro-2-path> …]) + [promotion candidate] when applicable

The automatic freeform write-in lets the user re-phrase a candidate before accepting or describe why they want to skip one.

Phase 4 — Edit specs/lessons.md

For each lesson the user confirmed in Phase 3, append a bullet under the ## Lessons section of specs/lessons.md. Bullet shape:

- <lesson text> — captured from `specs/<date>-<slug>/retrospective.md`[, `specs/<other-date>-<other-slug>/retrospective.
Read the complete source ↗