Skip to content

skills: a design document's rules get no check that can disagree with them #1168

Closed

Description

@OmarAlJarrah

Problem

morphic-reviewing-prs has no pass that can disagree with a design document. Its passes assume a
change has outputs to compare: "Behaviour against main" compiles a spec on both sides and re-plants
mutants, and "Claims" checks each statement against the tree. A change to docs/emitter-design.md
describes code that does not exist yet, so the first has nothing to run and the second can only
confirm names and citations.

morphic-changing-the-ir's design-rule-over-its-document is the nearest rule, and it asks that a
new rule be checked against the fields and steps of its own document. It does not ask that rules be
checked against each other, against a format the change was not written for, or against real input.

On #1167 the passes as written found no defect in the rules themselves, with citations, names and
cross-references all clean. Three procedures the skills do not state found the defects:

  • Reading the rules against each other and against another protocol: a gRPC stream fell to a
    fallback that overrode its own framing, and a second method's condition missed a file primary.
  • Running the proposed rules as a throwaway program over compiled specs: it measured each default,
    and a planted defect showed the program reacts.
  • Compiling the document's own samples under go vet, as doc-code-obeys-own-rules already says,
    though no review pass names it: vet refused an error type that compiled.

Direction

A proposal: a pass in morphic-reviewing-prs, or a rule its Claims pass cites, for a change whose
subject is a normative document:

  • list the rules the change states, and apply each to the cases of every other, and to one format
    or protocol the change was not written for;
  • where rules can be read as a function of a compiled document, run them over the corpus, and plant
    a defect to show the run reacts;
  • extract each code sample from the final text and run the document's own checks on it.

Out of scope

Reviews of Go changes, which the existing passes cover.

Related: #1160, which asks the same of an edited skill rule, and #1167

Priority: P4, rule 1 (a skills task that changes no lowering, validation, IR or emit-contract behaviour).
grep -nE 'design doc|docs-only' .claude/skills/morphic-reviewing-prs/SKILL.md → no match (morphic @0958eaf8).

Activity

  1. added
    type:featureNew capability or enhancement
    priority:P4Refactors, tests, CI, hostile-input hardening, cosmetic diagnostics, other formats
    on Oct 30, 2026
  2. self-assigned this
    on Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

priority:P4Refactors, tests, CI, hostile-input hardening, cosmetic diagnostics, other formatstype:featureNew capability or enhancement

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions