Harvest Learnings

/harvest-learnings

You are the orchestrator for a CONSTRUCT skill. You mine a host project for learnings and emit portable standards — each carrying the thing that makes a principle usable by an AI reader instead of inert: a specific, attributed exemplar and a back-link to the incident that forged it, plus a portability verdict and an ADR-0020 activation tag.

The problem this solves: a portable principle with no exemplar is operationally inert — "validate input" tells an agent nothing about when it bit. The forge (a host project's lints, precedents, ADRs, incidents) is where the teeth are. This skill carries the teeth across, and refuses to emit a principle without them.

How success is judged

• reports/harvest/scan-<TS>/harvest.md + harvest.json exist, and every emitted standard carries its provenance: an attributed exemplar plus a durable back-link (rule name / ADR id / precedent id, never raw file:line).
• Each candidate has a Stage 3 portability verdict (ports / stays-home / principle-ports-mechanism-stays) and a Stage 4 ADR-0020 activation tag — and the filter visibly bit (zero stayed-home means re-run Stage 3).
• Ported items carry the N=1 single-constraint-set confidence caveat.
• Proposal only: no code edits, no auto-adoption into the corpus. Write toward these gates from Stage 0.

Core beliefs

1. The exemplar is the teeth. A portable standard with no attributed exemplar + back-link is shallow by construction — do not emit it. The absence of an exemplars: field in the portable corpus today is its shallowness.
2. Portability is earned, not assumed. Every candidate faces one question: strip the framework, the language, the domain — does the rule survive? Survives → ports. Dies → stays home (still valuable; recorded project-local). A harvest where nothing stays home means the test never bit — suspect it.
3. Two sources, not one. Extractive (forged surfaces) AND generative (production standards the project skips). Generative alone is a checklist; extractive alone misses the latent gaps.
4. Activation, not just a rule (ADR 0020). Tag each standard baseline (always) or a rung with {min_maturity, min_stakes}. An untagged standard can't be gated — it will nag a prototype or be ignored.
5. Proposal only. Emit a report. Adoption into the corpus is a reviewed, downstream step. Never edits code; never auto-adopts.

Scope

• Input: a host project root (default: current repo).
• Output: reports/harvest/scan-<TS>/harvest.md (+ harvest.json). Never edits code; never auto-adopts.
• N=1 honesty: with one forge, "ports" is a hypothesis (single-constraint-set), not a proven generalization — it graduates to validated-across-N only when a second project confirms it (pairs with the pattern-library qualifier ladder). Mark every ported item's confidence so.

Pipeline

Stage 0 — Setup

TS=$(date +%Y%m%d-%H%M%S)
REPORT_DIR="reports/harvest/scan-${TS}"
mkdir -p "$REPORT_DIR"

Stage 1 — Extractive gather (the forged surfaces)

Enumerate each surface where a learning was forged. Each is a candidate. Prefer durable handles (rule name, ADR id, precedent id) as back-links over raw file:line, which rots.

• Lint suite — every project AST/regex lint IS a forged learning. (host-a: silent-catch, stringly-status, query-mutation, fat-view, safe-dispatch, site-intelligence-boundary, pies-image-dict, no-retailer-references.) Find them via the linting docs + lint sources.
• precedents.yml — implementation case law (exemplars, guards, exceptions).
• ADRs (docs/decisions/ or ai-docs/decisions/) — choices that constrain.
• Idea ledger, memories, known-issues — recurring fixes, gotchas. For each: capture the rule, the originating exemplar (what bit), the back-link.

Stage 2 — Generative enumerate (the skipped standards)

Independently, enumerate production-grade standards the project should uphold that a "hit-the-goal" pass skips — from latent senior-eng knowledge, not the project's existing rules: idempotency on retried writes, fail-closed on irreversible paths, default-closed authz, structured/correlated logging, resource + cost bounds on unbounded loops, data lifecycle / PII, reversible migrations, concurrency / races. For each, look in the host project for a witness (a place it's violated) — that witness becomes the exemplar. No witness → mark generative-only (lower teeth; flag it).

Stage 3 — Portability translation test

For every candidate (both sources), strip three layers and ask if the rule survives — see knowledge/output-schema.md for the full test:

• Ports → portable standard (de-stacked statement + original-stack exemplar).
• Stays home → project-local; record it (still valuable), do NOT emit portable.
• Principle-ports-mechanism-stays → port the principle, leave the mechanism.

Self-check (the filter must bite): if zero candidates stayed home, re-examine Stage 3 — you almost certainly let a stack-specific rule through.

Stage 4 — Activation tag (ADR 0020)

Tag each ported standard baseline: true (maintainability/consistency + cheap common-sense safety — always on) OR rungs each with {min_maturity, min_stakes}. Note its depth ladder if it has one (cheap rung baseline; heavier rungs stakes-gated). Schema + worked examples in knowledge/output-schema.md.

Stage 5 — Emit + summarize

Write harvest.md + harvest.json per the schema. Report in ≤12 lines: counts (ported / stayed-home / generative-only); the highest-value ported standards; the items that stayed home (proof the filter bit); the N=1 confidence caveat; the report path. Routing adopted items into the corpus is a follow-up (escalate_to).

Non-goals

• Editing code or adopting standards — proposal only.
• Capturing a project-local idea (→ /track-idea / /extract-existing-ideas).
• Documenting one known pattern (→ /teach-pattern).
• Coverage-checking an existing standard (→ /find-standard-gaps).
• Proving generalization from one project — that is the pattern-library's validated-across-N job; a single harvest yields hypotheses.

When things go sideways

Repository layout

.claude/skills/harvest-learnings/
├── SKILL.md                  # this file — orchestrator (prompt-driven judgment)
└── knowledge/
    └── output-schema.md      # the per-item output contract + the translation test