Skip to main content

​
Update mechanism: how new lessons flow in

This page covers how new lessons enter this repo. The repository began with one seed case study and now includes a second evidence-backed ship. The mechanism has three sources: per-ship retrospective, reader-submitted issues, and quarterly landscape audit. Source: REVIEWER G11; LESSONS itself as the seed instance.

​
Per-ship retrospective

A retrospective is a ship’s own debrief. It is written AFTER the ship lands; it documents what worked, what failed, what the existing canon missed, what the ship added. The v2.2 lessons report — the document we cite as LESSONS (see Overview → Sources) — is the seed instance of this format. It enumerates per-skill load-bearing analysis, patterns the existing meta-skills do not cover, the brainstorming-spec-plan-execute pipeline as gestalt, RED-GREEN-REFACTOR for prose, and case studies of reviewer-driven fix-ups. The shape is a reference for what a retrospective looks like.

​
Case-study shape

A case study lives at case-studies/<date>-<ship-name>.md. The date is in YYYY-MM-DD format; the ship name is a short slug. Sections in a case study:
  • Ship summary. What shipped. One paragraph.
  • The architectural cut (if any). A non-obvious design choice the audit did not name. The v2.2 case study’s sources/ deletion is this section.
  • The decoration-to-mechanism wirings. For stateful or rule-bearing skills, the specific commits that turned prose-as-wish into script-as-contract.
  • Reviewer-driven fix-ups. The per-commit narrative of what the reviewer caught. Cite commits explicitly.
  • What worked. Patterns that paid off. Name them with their cross-link to the relevant doc.
  • What failed. Patterns that did not. Name what would have caught the failure.
  • What the existing canon missed. The gap the ship’s lessons fill (the patterns the existing meta-skills do not cover).
  • What we missed. Honest list of things the ship did not catch and known imperfections.
When a ship includes a model benchmark, add a small machine-readable evidence manifest beside the case study. Record the frozen snapshot, run count, exact configurations, deterministic and semantic scores, exclusions, protocol amendments, interpretation limits, and hashes of retained raw artifacts. The provider-aware ingest case study is the worked example. The v2.2 case study is the worked example.

​
Reader-submitted issues

The repo accepts issues for:
  • Pattern requests. A reader has observed a pattern in their own ship and thinks the repo should document it.
  • Correction requests. A reader notices a factual error or stale information.
  • Cross-platform updates. A harness changes its behavior; the repo’s coverage should update.
  • Anti-pattern submissions. A reader has observed a failure mode; the repo’s catalog should add it.
The repo does NOT accept:
  • PRs that rewrite the project’s voice. Voice is an editorial choice, not a per-PR negotiation.
  • PRs that add LLM-specific magic. The repo is cross-platform; vendor-specific patterns live in docs/11-cross-platform/.
  • PRs without ship evidence. Every pattern in the repo cites a real commit or a real failure mode. Aspirational patterns (in principle this would help) are out of scope.

​
Quarterly landscape audit

The skill-authoring landscape changes faster than any single ship. The Anthropic skills repo gains new categories; Codex CLI adds features; new harnesses appear; existing harnesses change defaults. A quarterly audit catches drift. The v2.2 ship’s landscape report — LANDSCAPE in our citations (see Overview → Sources) — is the seed instance. It enumerates state of the art, who is writing skill-authoring guides, the harness landscape, anatomy of a “good” skill, anti-patterns observed in the wild, the quality bar for 2026, source catalog. The audit cadence: every quarter, re-fetch the canonical sources (agentskills.io spec, Anthropic Claude Code docs, superpowers, the major harnesses’ docs). Compare against the repo’s current claims; file issues for divergence; update the docs.

​
When a lesson lands in the repo

A lesson moves from “observed in a ship” to “documented in this repo” through one of three paths:
  1. Reviewer-driven from a case study. The ship’s case study is reviewed; patterns it surfaces become candidate doc updates.
  2. Issue-driven from reader submission. A reader files a pattern request; the maintainer reviews and either adds it or declines with rationale.
  3. Audit-driven from the quarterly landscape. The audit catches drift; updates ship as a maintenance commit.
In all three paths, the lesson must cite ship evidence (a commit, a failure mode, a verbatim source). The LESSONS and LANDSCAPE reports for v2.2 are the prototype: every claim has a source path or a commit SHA.

​
What the current corpus ships

The current corpus ships:
  • Two case studies (karpathy-wiki v2.2 and the provider-aware ingest ship).
  • The patterns those ships surfaced: decoration-vs-mechanism, prose-as-code, subagent reformatting, cross-script regression, spec arithmetic, TDD inversions, provider-neutral runtimes, and benchmark integrity.
  • The cross-platform reference frame (Claude Code, Codex, Gemini CLI, others).
  • The hero framework (the three-question framework).
  • The blocker docs (Quickstart, Mental Model, Token Economics).
  • The loader skill.
  • The minimal example skill.
Future ships can graduate repeated patterns once at least three independent ship samples exist, formalize more of the retrospective template, and add CI for SKILL.md validation. See the planning backlog for deferred work.

​
Sources

  • REVIEWER G11 (per-ship retrospective format).
  • LESSONS itself (the v2.2 lessons report as the seed retrospective instance).
  • LANDSCAPE itself (the 2026-04 landscape audit as the seed quarterly-audit instance).
Cross-links: v2.2 case study, provider-aware ingest case study, Benchmark integrity.