name: skmtc-retro-review\nversion: 0.1.0\ndescription: |\nAggregate friction log files across a time period to identify recurring\npatterns, classify each cluster by intervention type, produce a\nprioritized action plan with success criteria, and calculate convergence\nmetrics. Complements skmtc-retro (which captures per-session signal)\nby acting as the system's actuator: turning accumulated observations into\ndecisions. The primary output is a review document that makes the \"is it\ngetting better?\" question answerable.
Use this skill when the user asks to \"review retros\", \"review friction\",\n\"run a retro review\", \"what's the pattern across sessions\", \"what should\nwe fix next\", or on a periodic cadence (monthly, pre-release). Also run\nafter a cluster of sessions on the same feature area to surface systemic\nissues before they compound.
\nDistinct from skmtc-retro — that skill captures per-session\nobservations; this skill synthesizes them into decisions. Do not run\nthis skill as a substitute for a per-session retro.\nallowed-tools:
The friction log is a sensor. This skill is the actuator. Its job is to\nread accumulated observations, detect patterns the per-session view cannot\nsee, classify each pattern by what kind of intervention would eliminate it,\nand produce an action plan the user can execute.
\nWithout this skill, the friction log is a cemetery: observations accumulate\nbut nothing systematically improves. The review closes the loop.
\nScheduled cadence (recommended):
\nOn-demand:
\nSkip if:
\nFriction log:
\n<skmtc-root>/skmtc/deno/docs/friction-log/\nReview output:
\n<skmtc-root>/skmtc/deno/docs/friction-log/reviews/\nCreate the reviews/ subdirectory if it doesn't exist.
Review filename:
\n<YYYY-MM-DD>-review-<period>.md\nWhere <period> is a human-readable date range: 2026-05 (monthly),\n2026-Q2 (quarterly), or 2026-05-12-to-05-14 (targeted).
Examples:
\n2026-05-15-review-2026-05.md2026-05-15-review-pre-v0.5.md*.md files, excluding CLAUDE.md,\nREADME.md, discrepancy-catalog.md, and anything in reviews/.YYYY-MM-DD prefix falls\nwithin the review period. For a monthly review, include all files from\nthat month plus any older files with open entries.For each retro file, extract:
\n# heading)## Knowledge acquired tables if present)open, resolved <date>, superseded, wontfixDo not try to re-derive the root cause from entry bodies at this stage —\nextract the structured fields first, then read bodies only for entries you\nintend to cluster.
\nWith many files, read the ## Index table first (it's a summary of the\nwhole file). Read entry bodies only for entries that survive initial\nfiltering. This avoids loading the full text of every historical file.
Clustering is the hardest step and the most error-prone. The goal is to\ngroup entries that share a root cause, not just a surface topic. Two\nentries about \"import registration\" may have completely different root\ncauses; two entries that look unrelated (e.g., \"error message was unclear\"\nand \"I had to read the source to understand X\") may share the root cause\n\"API behavior is not legible from its interface.\"
\nGroup by root cause, not by topic. Ask: \"Would fixing X also fix Y?\"\nIf yes, they belong in the same cluster. If not, keep them separate even\nif their surface topic is the same.
\nA cluster must have at least 2 entries from different sessions (or 1\nentry classified as [blocker]) to warrant action. Single-session\nsingle-occurrence friction may be genuinely incidental.
One entry can belong to multiple clusters if it has multiple root\ncauses. Prefer the most specific cluster.
\nExplicitly note your clustering hypothesis in the review. \"I'm\ngrouping these because I believe they share root cause X\" — this lets the\nuser push back if the grouping is wrong. Do not present clusters as facts.
\nUnclustered entries — entries that don't fit any cluster — are still\nworth listing. Single-occurrence blockers in particular get their own\ncluster even without a second instance, because their severity warrants\nattention.
\nFor each cluster before writing the review:
\nCluster: <short name>\nRoot cause hypothesis: <one sentence>\nEntries: <file>#<N>, <file>#<N>, ...\nSeverity range: <lowest> to <highest>\nResolved entries: N of total\nFor each cluster, classify by intervention type using the decision tree\nbelow. Work through the questions in order — higher-ranked interventions\nare more permanent than lower-ranked ones.
\n1. Can this be eliminated by invariant enforcement (tooling)?
\nThis is the highest-leverage intervention. A mechanically-checked rule\ncannot be violated silently; documentation can.
\nCandidates:
\ndoctor check or bundle-time lint rule.deno lint plugin or\npre-bundle validation step.If tooling is feasible: recommend a specific check (what it tests, what\nerror it produces, where it runs). Label intervention type: tooling.
2. Is this a footgun in the API design?
\nA footgun is an API that is easy to misuse in a way that compiles and runs\nbut produces wrong output. Examples: ImportNameArg object form producing\nunexpected aliasing; .isRef() ? resolve() : schema ternary being\nredundant because the non-ref variants also implement .resolve().
Footguns cannot be fully fixed by documentation — the fix is normalization,\ntightening the type to block invalid input, or a better runtime error.
\nIf a footgun: recommend the specific API change (normalize the edge case,\nrestrict the type, add a runtime guard). Label: skmtc-code.
3. Is this a missing runtime capability (architectural limit)?
\nWhen the task genuinely cannot be done with the current API — not a\ndocumentation gap, but a structural absence. Example: the\none-operation-to-many-forms blocker that required the operation-variant\naxis in @skmtc/core@0.5.0.
These are the most expensive to fix but also have the highest impact.\nIf it's an architectural limit: flag for core roadmap with a description\nof what the API surface should look like. Label: skmtc-core-feature.
4. Is this a wrong LLM prior about SKMTC behavior?
\nThe LLM's training data includes many frameworks. It applies defaults from\nthose frameworks to SKMTC. When the SKMTC behavior differs from the prior,\nfriction occurs even when the behavior is correctly documented — because the\nLLM didn't reach for the docs.
\nSkill updates override priors at task time. They are most effective when\nthey name the prior explicitly: \"In TypeScript you would do X. In SKMTC\nyou do Y instead, because Z.\"
\nIf a wrong prior: add an operational principle to the relevant skill with\nthe pattern \"In <other> you would... In SKMTC you... because...\". Label:\nskill-update.
5. Is this a knowledge gap in docs?
\nThe agent had to discover correct behavior by trial, reading source, or\nasking the user — and the answer exists nowhere in docs or skills.
\nSub-types:
\nAlso consider adding the knowledge to skmtc agent-context output — if\nan agent starts briefed with this fact, the friction never occurs. Label:\ndoc-update, agent-context, or doc-discoverability.
6. Is this a missing worked example?
\nSome principles are best taught by a concrete, working example rather than\na rule. If the friction repeatedly occurs despite the rule being documented,\nthe rule alone isn't working — add an example.
\nExamples live in test fixtures, an examples/ directory, or inline in\nskill entries. The example must be a complete, real, runnable snippet —\nnot pseudocode. Label: example-addition.
7. Should this API or generator be removed?
\nSometimes the right fix is deletion. If an API creates persistent footguns\nwith no clean fix, or a generator's design is fundamentally incompatible\nwith SKMTC's regeneration contract, removing it is higher leverage than\ncontinuing to document around it. The GraphQL thin-wrapper generators were\ndeleted rather than fixed.
\nRecommend removal only when: (a) the API is a persistent source of friction\nacross multiple sessions, (b) a skill/doc fix has already been attempted and\ndidn't eliminate recurrence, and (c) there is an alternative approach.\nLabel: removal.
| Label | \nWhat it is | \n
|---|---|
tooling | \nDoctor check, lint rule, bundle-time validation | \n
skmtc-code | \nBug fix or API normalization in @skmtc/core or a gen-* package | \n
skmtc-core-feature | \nNew capability needed in @skmtc/core | \n
skill-update | \nNew or modified operational principle in a skill | \n
doc-update | \nNew or expanded content in API reference or how-to docs | \n
agent-context | \nAdd fact to skmtc agent-context output | \n
doc-discoverability | \nImprove cross-referencing or surfacing of existing doc | \n
example-addition | \nAdd a worked example to a test, examples dir, or skill | \n
removal | \nDeprecate or delete the problematic API or generator | \n
Calculate these metrics for the review period and append a row to the\nmetrics history table in the review file.
\nThe primary convergence signal.
\nFRR = recurrent entries / total entries (for the period)\nA \"recurrent entry\" is one where the same root cause was logged in a prior\nperiod and the prior instance has status open (no intervention was made\nor the intervention didn't work).
Blocker% = blocker entries / total entries\nConvergence looks like: Blocker% → 0, then Friction% → 0, leaving\nonly Polish% and eventually silence. If Blocker% is flat or rising,\nthe system is not converging at the structural level — code changes are\nneeded, not just docs.
Total open entries (all time) = sum of unresolved entries across all files\nThis number should not grow unboundedly. If it grows faster than entries\nare resolved, the action loop is too slow. A target: open entries should\nhalve within two review cycles after a recommendation is acted on.
\nKnowledge backlog = count of \"Knowledge acquired\" rows across all retro\n files whose doc implication is not \"none\" and whose\n content has not yet been added to docs/skills\nThis measures how much extracted intelligence remains un-acted. A large\nbacklog means the retro → doc pipeline is blocked somewhere.
\nResolution velocity = average days from entry creation to resolved status\n (for entries resolved in the review period)\nLong velocity (30+ days) indicates the action loop is slow — typically\nbecause \"recommended action\" stays in a review doc without being assigned\nor prioritized. Short velocity (< 7 days) is ideal.
\n# Friction Review — <period>\n\n**Reviewed:** <YYYY-MM-DD>\n**Period:** <date range>\n**Sessions included:** N\n**Files read:** <list of filenames>\n\n## Summary\n\n| Metric | Value | vs. prior period |\n|--------|-------|-----------------|\n| Total entries | N | +N / -N |\n| Blocker% | X% | ↑ / ↓ / — |\n| Friction Recurrence Rate | X% | ↑ / ↓ / — |\n| Total open entries (all time) | N | +N / -N |\n| Knowledge backlog | N items | +N / -N |\n| Resolution velocity (period) | N days avg | |\n\n## Convergence signal\n\n<2-3 sentences. Is the system converging, flat, or diverging? What's the\ndominant pattern? Be direct — \"FRR is 60% and flat; skill updates are not\nreaching the root cause\" is more useful than \"mixed results.\">\n\n## Clusters\n\n| # | Cluster | Root cause hypothesis | Sessions | Severity | Open | Recommended intervention |\n|---|---------|----------------------|----------|----------|------|--------------------------|\n| C1 | <name> | <one sentence> | N | blocker/friction/polish | N/total | <label> |\n\n## Action plan\n\n### P1. <Intervention label> — <Cluster name>\n\n**Root cause:** <one sentence>\n**Evidence:** <file>#<N>, <file>#<N> (N total instances)\n**What to do:** <specific, actionable change — not \"improve docs\" but \"add\na note to §import-registration in the generator skill explaining that the\nobject form of ImportNameArg always produces `name as alias` output, even\nwhen alias is omitted, and the bare string form is correct for non-type\nnon-aliased imports\">\n**Success criterion:** <falsifiable condition — \"subsequent retro files\nshould contain zero entries about ImportNameArg object form misuse\">\n**Verification:** check the next 2-3 retro files after the change for\nrecurrence of this pattern\n\n---\n\n### P2. ...\n\n## Knowledge backlog\n\nItems from `## Knowledge acquired` tables not yet reflected in docs/skills:\n\n| Source | Item | Doc implication | Priority |\n|--------|------|-----------------|----------|\n| <file> K1 | <what was learned> | <skill/doc/agent-context> | high/medium/low |\n\n*If backlog is empty: \"All knowledge-acquired items from this period are\nreflected in current docs and skills.\"*\n\n## Metrics history\n\n<!-- append one row per review; do not delete prior rows -->\n\n| Review date | Period | Sessions | FRR | Blocker% | Open (all time) | Knowledge backlog | Actions completed |\n|-------------|--------|----------|-----|----------|-----------------|-------------------|-------------------|\n| <YYYY-MM-DD> | <period> | N | X% | X% | N | N | N of N prior |\nThe ## Metrics history table accumulates across reviews — append one row\nper review cycle, never delete prior rows. This is the convergence record.\nIt is the only place where the trend question (\"is it getting better?\") can\nbe answered empirically rather than by impression.
If no prior review file exists, create the table with one row. Future\nreviews append to the same table in the same file, or to a new review file\nthat cross-references the prior one with a link.
\nOrder the action plan by:
\ntooling > skmtc-code > skmtc-core-feature > skill-update > doc-update > example-addition[friction]\nentries outranks 1 [friction] entry; a [blocker] outranks multiple\n[friction] even at the same type level.Every action plan entry must name:
\nVague recommendations (\"improve documentation of X\") are not actionable and\nwill not close the loop. Specific recommendations (\"add the following\nparagraph to §3 of skmtc-generator SKILL.md, under the register API\nsection:...\") can be completed in minutes.
Before drafting new action items, check the most recent prior review file\n(if one exists) and answer:
\nRecord this follow-up as the first section after the summary in the new\nreview file.
\nFull flow:
\n## Knowledge acquired rows\nfrom the period's retro files. Check each against current docs/skills to\nsee if it's already been addressed.Review written to <filename>. N clusters, top intervention: <P1 label — cluster name>. FRR: X% (prior: Y%). <convergence signal sentence>.The user decides which action plan items to execute. The review skill does\nnot execute them — it produces decisions. Each action item is a unit of\nwork for the relevant skill (skmtc-generator, skmtc-cli, docs editing,\nor filing a SKMTC code issue).
When an action item is completed, update the corresponding retro file\nentries' **Status:** lines and the ## Index rows. Also update the\nreview file's metrics history row for the period (if the resolution\nhappened within the same period).
The next review cycle opens with §8 \"Prior action follow-up\" to verify\nthat completed items actually eliminated the friction. This is the\nfeedback loop that drives convergence: observe → cluster → intervene →\nverify → observe.
\nThe convergence guarantee: the system converges when every friction\ncluster, on recurrence, triggers escalation to a higher-permanence\nintervention. Friction that doesn't yield to docs must be taken to\nskill-update. Skill-updates that don't eliminate recurrence must be\ntaken to code. Code changes that are blocked must be taken to the\nroadmap. Clusters that cannot be addressed at any level are candidates\nfor removal of the offending API or feature. With this escalation\ndiscipline, every class of friction either gets eliminated or gets\nexplicitly accepted as a known cost — neither outcome leaves the system\nin an unexamined drift state.
\n","files":[{"path":"commands/skmtc-retro-review.md","sizeBytes":3713,"isText":true},{"path":"design.md","sizeBytes":8486,"isText":true},{"path":"SKILL.md","sizeBytes":21392,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-18T13:28:42.703507Z","sha256":"ACC80E503786DEFEB2F40FB7766E5346ADB82D71FE7AB625AC7778C92F89407E","sizeBytes":14328},"review":null,"source":{"repositoryUrl":"https://github.com/skmtc/skmtc","path":"deno/docs/skills/skmtc-retro-review","license":"Apache-2.0","commit":"e3abffcbfd1109c694656742d3a49491dbf86b92","subtreeSha":"2009A71ABF40A6126DE23619401487BE0D2D3B8F0F2FD5D7D36783C5BEA7443D","lastSyncedAt":"2026-09-27T19:30:42.792127Z"},"reviewedAt":"2026-09-18T13:31:42.548969Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/skmtc/skmtc/tree/main/deno/docs/skills/skmtc-retro-review"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install skmtc-skmtc@llmmart"},{"target":"git","command":"git clone https://github.com/skmtc/skmtc.git"}]}