Skip to content

skills: add triage-issue, for judging an issue against the architecture - #167

Merged
Yaraslaut merged 1 commit into
masterfrom
skill-issue-triage
Aug 23, 2026
Merged

skills: add triage-issue, for judging an issue against the architecture#167
Yaraslaut merged 1 commit into
masterfrom
skill-issue-triage

Conversation

@Yaraslaut

Copy link
Copy Markdown
Member

Adds .claude/skills/triage-issue/SKILL.md. Repo-specific by design — the value is in morph's own invariants and morph's own worked examples, not in generic triage advice.

Why

Roughly a third of the issues acted on recently needed something other than what they asked for. Not carelessness: a symptom seen from inside one layer reads as a framework gap when it is really the architecture working.

Each was caught by the same few questions asked in the same order. So they are written down.

What's in it

Seven architecture invariants, each having already caught a real mis-framed issue, each cited to its authoritative source rather than to the skill file — a model does not know the framework exists and is single-threaded per ModelId; a requirement on consumers must compose rather than inherit; the value type reports the fact and the layer decides the policy; templates parameterised on application types are the design; spec-vs-code disagreement is itself the finding; a guarantee reimplemented per call site belongs in one place; and "would this still pass if the feature did nothing?"

The step it puts hardest is checking the premise empirically before evaluating the fix. That is the step that has changed the most verdicts and the one most often skipped. An issue reasoned out from reading source is a hypothesis; ten lines usually settles it.

Five worked examples with the actual evidence — including what the experiment turned out to be — so a reader sees the shape of a triage, not just its rules.

A failure-modes section recording two mistakes genuinely made here: undoing a deliberate fix without reading its history (the per-commit cache key existed to stop branches deleting each other's caches), and verdict-by-assertion.

Labels

Six triage: verdicts and ten area: labels, with the gh label create commands. Already created on the repo, and the verdicts established this session are already applied to 20 open and closed issues — so the taxonomy arrives populated rather than theoretical.

Verification

Every quoted source in the skill was checked against the file it cites; one quote didn't match and was corrected to the spec's exact wording rather than left as a paraphrase. Every issue number cited was checked to exist and match the described verdict.

Roughly a third of the issues acted on recently needed something other than
what they asked for -- not through carelessness, but because a symptom seen
from inside one layer reads as a framework gap when it is really the
architecture working. #129 asked for a seam that must not exist, #92's
premise was false, #86's growth law was wrong, #150 solved half its problem
with the wrong mechanism. Each was caught by the same few questions, asked
in the same order, so the questions are worth writing down.

The skill encodes seven architecture invariants, each one already having
caught a real mis-framed issue, each cited to its authoritative source
rather than to this file:

- a model does not know the framework exists, and is single-threaded per
  ModelId, so the unit of later work is another action;
- a framework requirement on consumers must compose, not inherit;
- the value type reports the fact, the layer decides the policy;
- templates parameterised on application types are the design, not an
  accident of it;
- spec and code disagreeing is itself the finding, not licence to pick a
  side;
- a guarantee reimplemented per call site belongs in one place -- count the
  copies before proposing or rejecting a primitive;
- would this still pass if the feature did nothing?

The step it puts hardest is checking the premise empirically before
evaluating the fix, because that is the step that has changed the most
verdicts and the one most often skipped. An issue reasoned out from reading
source is a hypothesis.

Verdict labels (triage: valid / rescope / wrong-layer / unverified /
invalid / parked) plus area labels, with the gh commands to create them.
The verdicts this session established are already applied to the open
issues.

Five worked examples carry the real evidence, including what the experiment
turned out to be, so the next reader can see the shape of a triage rather
than only its rules. The failure-modes section records the two mistakes
actually made: undoing a deliberate fix without reading its history, and
verdict-by-assertion.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@Yaraslaut
Yaraslaut merged commit 61a5b5a into master Aug 23, 2026
24 checks passed
@codecov

codecov Bot commented Aug 23, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant