Separate register from altitude in the create-issue skill, and enforce it at review

[jeffhorn-nava]

What we decided

Two related improvements to the create-issue skill, both learned from reviewing how the skill reframed a decided, detailed technical issue (#1) into the plain-English epic #6.

1. Name register and altitude as two independent choices. Register is how technical the wording is (plain versus technical). Altitude is the scope and type of the issue (epic versus technical-task). The skill currently biases toward dropping altitude with its step 1 rule "prefer the less technical one," and nothing counterbalances it. When reframing already-decided work to a higher altitude, the author should make a deliberate, per-item choice for each decided detail: preserve it inline, spin it out into a linked technical-task, or intentionally drop it. Shedding detail should be a conscious decision, not an accident of wording.

2. Enforce that preserve-or-spin-out discipline at the review checkpoint (step 4), not only in the authoring steps. Today step 4 delegates to review-draft, which checks quality, voice, punctuation, template adherence, and house style. It is stylistic only, so an over-plain reframing that silently drops decided content passes review unflagged. Add a substantive gate so the reviewer confirms the altitude and register transform was deliberate.

What's already been explored

These two improvements came out of an adversarial review comparing issue #1 (a decided technical write-up) against issue #6 (the epic the skill produced from it). The review confirmed the epic framing itself works: an agent could infer a sound implementation plan from #6 and the repo alone. The gap was narrower than it first looked. It is not that the skill loses information, but that it has no explicit discipline for choosing what to shed when it raises altitude, and no review gate to confirm that choice was intentional. A naive "keep everything" check was rejected as wrong for epics.

Starting point

• File / location: skills/create-issue/SKILL.md (step 1, the "prefer the less technical one" rule; step 4, the review handoff)
• Key function, class, or module: skills/review-draft/SKILL.md (the review step is stylistic today; the new fidelity gate lives here or is called from create-issue step 4)
• Run with: this is skill and documentation editing, not a script; validate by re-reading the two SKILL.md files against the templates

Definition of done

• create-issue SKILL.md distinguishes register (wording) from altitude (scope and type) as independent choices
• Guidance covers reframing decided work: per decided item, preserve inline, spin out to a linked technical-task, or intentionally drop
• The preserve-or-spin-out discipline is enforced at the review checkpoint, not only stated in the authoring steps
• review-draft (or create-issue step 4) gains a substantive fidelity check for altitude and register transforms, distinct from its stylistic checks

Constraints and gotchas

• A naive completeness check ("keep all detail") is wrong for epics: shedding implementation detail is the intended effect of raising altitude. The check must confirm the transform was deliberate, not that nothing was dropped.
• The guidance must stay register-appropriate. It should not push authors back toward agent-plan language inside product templates like epic and story.

Related

Findings from reviewing #1 against #6. Summarized in a comment on #6.

[jeffhorn-nava]

Heads-up: PR #31 (Closes #19) inserts a new "Check for duplicates" step as step 1 of skills/create-issue/SKILL.md and renumbers the rest. This issue's references now point at the wrong numbers: the "prefer the less technical one" rule this issue targets moved from step 1 to step 2, and the review handoff moved from step 4 to step 5. When this is picked up, refer to those rules by name rather than number so the reference stays stable.