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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jentic/jentic-api-scorecard --skill sdd-distill-lessons技能说明
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.mdonly — no other writes. This skill edits exactly one file.specs/tech-stack.mdpromotions are surfaced as user-actionable suggestions; the skill never editstech-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.mdbody 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 candidateverdict (yesornoplus 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.
阅读完整来源 ↗