Prospec Learn

---
name: prospec-learn
description: "Feedback Promotion Pipeline - Collect session corrections, repeated verify FAILs and recurring review criticals into a version-controlled lessons ledger; score them with an explicit, reproducible rule (frequency + impact modules); and promote - only with explicit human approval - across three tiers (accumulating ledger -> team playbook -> Constitution rule). Triggers: learn, promote lesson, playbook, 學習, 晉升教訓, 經驗手冊"
---
<!-- Generated by `prospec agent sync`. Do not edit — this file is regenerated on every sync. -->

# Prospec Learn Skill

## Activation

When triggered, briefly describe:
- That you'll collect recurring lessons from archived changes' quality_log and review.md into a version-controlled lessons ledger (auto-fed at archive time)
- That promotion is decided by an explicit, reproducible rule (not a black-box heuristic) and every suggestion carries an auditable score
- That nothing reaches the team playbook or Constitution without explicit human approval and a version-controlled record

## Language Policy

Write each generated document in the language the Constitution's Language Policy rule assigns to **its path** — change artifacts and their archived summaries in the project's artifact language, the trust zone (Knowledge base, Feature Specs, index) in English. One skill run may write both. Keep code, identifiers, technical terms, and git commit messages in English.
## CLI Prerequisite (required)

> The prospec CLI is a required file for this skill — its deterministic steps call `prospec`
> commands. Probe BEFORE any other step; there is no manual fallback.

1. Run `prospec --version` (Bash).
2. **Command not found / not executable** → STOP. Ask the user to install the prospec standalone
   executable — the one-click installer script from the project README (macOS/Linux `install.sh`,
   Windows `install.ps1`) or a release binary from GitHub Releases; prospec is NOT published to
   npm. Then re-run this skill.
3. **Version older than 2.0.0** → STOP. Report the installed vs required version
   and ask the user to upgrade, then re-run this skill.

Hand-executing a CLI-owned mutation is NEVER the fallback — that re-introduces the
nondeterministic serialization this contract exists to remove.

## Startup Loading

1. [STABLE] **MANDATORY** — Read [`references/promotion-format.md`](references/promotion-format.md) for the explicit promotion rule, the Generalizability Heuristic (what to capture), lessons-ledger format, playbook entry format, approval record, and TTL/conflict fields
2. [STABLE] Read `prospec/CONSTITUTION.md` — the promotion target (Constitution rules) and the duplicate-check baseline
3. [DYNAMIC] Read `prospec/ai-knowledge/module-map.yaml` — to compute each lesson's impact-module count
4. [DYNAMIC] Read the existing lessons ledger `prospec/ai-knowledge/_lessons-ledger.md` (if present) — carry-forward anchor (version-controlled, survives worktrees)
5. [DYNAMIC] Read `prospec/ai-knowledge/_playbook.md` (if present) **in full** — the Sweep's team-tier input and Promote's duplicate-check baseline. This is the one skill that reads the whole playbook; every other reader loads only the entries relevant to its change
6. [DYNAMIC] Read `.prospec.yaml` `learn.thresholds` (promotion) and `learn.lens_thresholds` (yield sweep) if set; otherwise use the reference defaults (the ledger itself is `prospec/ai-knowledge/_lessons-ledger.md`, not a config file)

## Entry Gate

> Blocking precondition check before this skill runs. If any item FAILs, stop and tell the user what is missing — do not proceed.

- There is material to learn from: at least one archived change exists under `.prospec/archive/` (with `metadata.yaml` quality_log and/or `review.md`) **OR** `prospec/ai-knowledge/_lessons-ledger.md` carries prior entries. Only when **both** are absent, stop and say there is nothing to collect yet. (The ledger is version-controlled, so a fresh worktree with a wiped `.prospec/archive/` but a populated ledger still has material — do not false-block.)
- The promotion rule is available: `references/promotion-format.md` loaded.
- Prior unresolved WARN: read the lessons ledger and surface any lesson already flagged "suggest promote" but not yet decided.

## Core Workflow

### Sweep

Runs FIRST — audit the two governed files for entries the project has outgrown, so this run keys new occurrences against a current ledger instead of adding evidence to a dead rule. Tests, evidence bar and removal semantics: `references/promotion-format.md` → **Staleness Sweep**.

- The mechanical half is already computed: `prospec learn upsert` reports playbook entries past their TTL review-by date (entries already retired are excluded). In addition, run `prospec learn yield`: a lens whose consecutive zero-yield changes reach the threshold (with enough invocations) is recommended `retire`; a lens whose yield ratio falls below the minimum is recommended `review`; a lens becomes eligible only once it has at least `min_invocations` **declared** runs (`--lenses` at merge time); a lens never declared stays `keep` (its invocation count is a rows proxy).
- The judgment half is the four tests — **mechanized** (a gate/test/type/check now enforces it), **no longer applicable** (the artifact, station, command or config it governs is gone), **contradicted** (it conflicts with a Constitution rule, a shipped spec, or a newer entry), and **desynchronized** (an entry annotated `Inlined into gate`/`Mechanized` whose later `Strengthened` clauses never reached the gate its `Landing:` anchor names). The first three propose retirement; **desynchronized** proposes re-syncing the gate or re-annotating, never retiring the still-valid entry.
- Evidence, not memory: name the mechanism (`file:line`, a `DRIFT_CHECK_IDS` id, a test name) **and its executor**, then confirm no occurrence postdates it. A checker nothing runs is not a mechanism, and a mechanized root cause does not by itself retire the entry that still states WHY — annotate that one instead. For **desynchronized**, read the entry's `Landing:` anchor, open each named gate, and point at the `file:line` where the strengthened clause is absent — a bare "looks synced" is not evidence.
- Present every finding on the **needs-review list** with its evidence and a proposed action, then stop for **explicit human approval** — retirement is a shared-tier write and carries the same approval discipline as promotion. Apply only what was approved; the rest stays listed.


### Collect

Build/refresh the version-controlled lessons ledger (`prospec/ai-knowledge/_lessons-ledger.md`):
- Scan each archived change's `metadata.yaml` `quality_log` and `review.md` for WARN/FAIL/critical findings; also fold in the session corrections the user raised that pass the **Generalizability Heuristic** (`references/promotion-format.md` → what to capture) — a one-off mock, business-string tweak or temporary hack is not folded in, so a manual `prospec-learn` run applies the same capture filter the L0 Checkpoint Correction Capture protocol does.
- Assign each finding a **deterministic key** (a normalized signature — e.g. the rule/REQ it relates to, or a file/pattern), so the same lesson maps to the same key every run. Semantic matching ("are these the same lesson?" → reuse the existing key) is the **only LLM step**.
- For each keyed finding, emit a lesson JSON (`{key, description, kind, source_change, impact_modules}` — `impact_modules` looked up from `module-map.yaml`) to a temp file and run `prospec learn upsert --lesson <file>` (Bash). The CLI owns the mechanics: keyed idempotent upsert, `frequency` incremented only for a DISTINCT source change (never recomputed by re-scanning), `source_changes[]`/`impact_modules[]` union, and the canonical table render.

### Score

The scoring runs INSIDE `prospec learn upsert` — the explicit numeric rule from
`references/promotion-format.md`, defaults overridable in `.prospec.yaml` `learn.thresholds`:
- **suggest promote** WHEN `frequency ≥ 3` AND `|impact_modules| ≥ 2` (a `kind: constitution` lesson routes to the Constitution tier; otherwise to `_playbook.md`).
- Below either threshold → stays personal, not suggested (avoids early noise when samples are few).
- The command emits the **auditable score detail** per suggestion (`frequency=N · impact_modules=M · kind=… · rule=freq≥3 ∧ modules≥2 ⇒ suggest`) — quote it verbatim when presenting; never re-derive the score by hand. Same ledger input ⇒ same output — the reproducibility guarantee, by construction.
- **Prioritize the review queue by knowledge freshness** (see promotion-format "Review-Queue Prioritization"): read the `prospec-report.json` file (`prospec check`) — its stale modules are `structural.knowledge_health.modules[]` filtered by `.stale` (there is no top-level `stale[]` array; shape: [`references/drift-report-format.md`](references/drift-report-format.md)); raise a `convention`-kind suggestion whose `impact_modules` intersect a stale module and annotate "this module's knowledge is also stale — refresh on hand-move". No report present → default order (non-blocking). Prioritization only — never auto-writes `_conventions.md`.

### Promote

**lessons ledger → team `prospec/ai-knowledge/_playbook.md` → Constitution**, gated stricter at each step. Routing by the lesson's **kind** (see `references/promotion-format.md`):
- **constitution** (hard, enforceable principle) → `prospec/CONSTITUTION.md` as a `ConstitutionRule` (RFC-2119 severity form) that `prospec-verify` grades.
- **convention** / **playbook** → `prospec/ai-knowledge/_playbook.md` — the single governed team tier (L2 on-demand + TTL). The `kind` label is recorded on the entry; a `convention`-labelled entry may later be **hand-moved** by a human into `_conventions.md` `prospec:user` section, but the pipeline **never auto-writes `_conventions.md`** (it is an L1 Core Convention read on every task and not TTL-governed).
- **contract test promotion** (generalizable invariant pin) → propose promoting review fix-loop regression pins that enforce structural, sanitization, or boundary invariants across an entire component family into permanent directory-enumerated contract tests in `tests/contract/`.

- A suggestion is **never written** to `_playbook.md` or the Constitution without **explicit human approval**. Present the score detail, ask, and only on approval write the entry.
- Every written entry is **version controlled** and records `source change(s)`, the `promotion criteria` that fired, the `kind`, and the `approver`.
- If the lesson duplicates an existing Constitution rule, propose **strengthening the existing rule** rather than adding a new one.
- If the user **rejects** a suggestion, record it as declined in the ledger and do not re-suggest it.

### Govern

- Every shared rule (playbook/Constitution) carries a **TTL** and a source reference.
- `prospec learn upsert` also reports playbook entries past their TTL review-by date — carry them onto the **needs-review list**. Rule **conflict** detection (including cross-author contradictory feedback) stays your judgment; both go to human retirement/arbitration — never auto-resolved, never silently dropped.
- Retiring a shared rule is version controlled with the reason and date — a ledger row keeps every counter and turns `status: retired` with a `｜ **Retired**:` suffix; a playbook entry keeps its provenance head, swaps TTL/Guidance for a `- **RETIRED {date}**:` line and moves under `## Retired Entries`. The audit that finds these entries runs pre-Collect (see **Sweep**); Govern records what the human approved there.

## Output Contract

> After running, self-assess and emit a concise Output Summary. Every Success Criterion must be objectively checkable (file existence / grep / count) — no subjective adjectives.

### Success Criteria
- [ ] the Sweep ran before Collect: every expired entry it found is on the needs-review list with a named mechanism/evidence and a recorded human decision
- [ ] lessons ledger `prospec/ai-knowledge/_lessons-ledger.md` written/refreshed with keyed entries (frequency, impact_modules, source)
- [ ] each "suggest promote" carries an auditable score detail (reproducible from the ledger)
- [ ] no team-playbook / Constitution write occurred without explicit human approval (manual)
- [ ] expired/conflicting shared rules surfaced on the needs-review list

### Failure Conditions
- a shared-layer or Constitution write happened without recorded human approval — retiring or editing an existing entry counts as such a write
- a promotion suggestion lacks a traceable score detail (black-box)
- a ledger row was deleted, or a counter changed, to tidy the file

### Output Summary
Emit one line: `Met N/M | Unmet: <items> | Overall: PASS|WARN|FAIL | Next: <one-line>`

### Exit Gate (Constitution)

Verify the output against this skill's **site-specific** rule (**promotion-approval discipline** — nothing reaches the team playbook or Constitution without explicit human approval), not the full Constitution; the every-principle audit is `prospec-verify` V3/5 only. When a rule carries RFC-2119 severity, grade by weight — MUST→FAIL, SHOULD→WARN, MAY→informational (the grade vocabulary stays PASS/WARN/FAIL). A free-text Constitution falls back to judgment-based grading. Record any WARN/FAIL (e.g. a promotion blocked, an unresolved conflict) to the change's `metadata.yaml` `quality_log` (`skill: prospec-learn` / `date` / `result` / `warnings`). Advisory — surface issues, do not hard-block.

## NEVER

- **NEVER** write to the team playbook or Constitution without explicit human approval — shared rules govern everyone; silent writes are unauditable and erode trust
- **NEVER** use a black-box heuristic for promotion — the decision must be an explicit rule over stored data so it is reproducible and reviewable (the project's differentiator)
- **NEVER** recompute frequency by re-scanning all archives each run — maintain an incremental counter in the ledger; re-derivation drifts and is non-reproducible
- **NEVER** auto-resolve a rule conflict or auto-pick between contradictory cross-author feedback — flag it for human arbitration
- **NEVER** silently sustain an expired or conflicting shared rule — it must appear on the needs-review list
- **NEVER** delete a ledger row, renumber a `PB-{NNN}` id, or change a counter to tidy either file — retire in place; `frequency` and `source_changes` are the only evidence the pattern was real
- **NEVER** raise a retired row's `frequency` with an occurrence that predates the fix that retired it — the counter would assert a live pattern; record such an occurrence in `description`
- **NEVER** suggest promotion from a single occurrence or negligible impact — that is early noise, not a pattern

## Error Handling

| Scenario | Action |
|----------|--------|
| No archived changes **and** empty ledger | Stop; report there is nothing to collect (accumulate lessons over more changes first). A populated `_lessons-ledger.md` alone is sufficient material — do not stop |
| module-map.yaml missing | Compute impact from delta-spec REQ prefixes instead; note reduced precision |
| `_playbook.md` absent | Sweep the ledger tier only and report the absent team tier — it is a **placeholder** convention doc (`init` registers it in `index.md` but deliberately does not create it), so it comes into existence when the first promotion is approved. Never scaffold it mid-run |
| An expiry claim cannot be evidenced (mechanism not found, or found with no executor) | Leave the entry active and list it as unresolved with what was checked — an unevidenced retirement is a silent rule deletion |
| Human approval not given | Leave the lesson at its current tier; record the pending suggestion, do not write |
| Promotion write fails | Do not silently drop; keep the queued suggestion and report the failure |