issue

name	issue
description	Write an executable issue pack that names the incoherence, source-of-truth, constraints, proof obligations, required skills, and implementation guidance without creating ambiguity or false closure.
artifact_class	runbook
kata_surface	external
governing_question	How does γ turn a selected gap into an issue pack that α and β can execute, verify, and close without hidden assumptions?
visibility	internal
parent	cdd
triggers	["issue"]
scope	task-local
inputs	["selected gap","mode","active design constraints","Tier 3 skills","affected surfaces","related artifacts","current implementation status"]
outputs	["executable issue pack"]
requires	["γ completed observe/select","canonical CDD.md loaded"]
calls	["issue/labels/SKILL.md","issue/contract/SKILL.md","issue/proof/SKILL.md","issue/constraints/SKILL.md"]
kata_ref	src/packages/cnos.cdd.kata/katas/M5-issue-authoring/

Issue

Core Principle

A coherent issue is an executable work contract. It names:

1. the incoherence;
2. the impact;
3. the status of the affected system;
4. the source of truth;
5. the implementation boundary;
6. the acceptance criteria;
7. the proof or rejection mechanism;
8. the non-goals.

A coherent issue lets an engineer who was not in the conversation act without asking clarifying questions.

Failure modes:

• ambiguity — engineer must ask what the issue means;
• overclaiming — issue states target/draft/spec behavior as if it already ships;
• false closure — issue has good prose but no proof or rejection mechanism;
• source drift — issue cites the wrong canonical doc, path, or runtime surface;
• scope leak — non-goals reappear inside acceptance criteria or work steps;
• exception theater — exceptions hide the rule instead of documenting temporary debt.

Operational shape:

Issue = tri(gap, execution boundary, verification surface)

The problem names the gap. The scope and constraints name the execution boundary. The acceptance criteria and proof plan name the verification surface.

---

Mode declaration and MCA preconditions

Every issue declares a mode in its body header. The mode tells α how much design work has already converged and how much α must do before implementation begins.

Mode	Meaning	When to use
MCA (Make-Coherent-Acceleration)	Design + plan already converged; α executes a known sequence	Both design and plan are committed at stable paths and will not be edited during the cycle
explore	Gap is real but boundary not yet bounded	The issue names a problem that needs investigation before implementation
design-and-build	Design needed before code; both happen in this cycle	Small enough that staging a separate design cycle would be overhead
docs-only	No code change, no version bump	Retroactive close-out, self-coherence report, doc cleanup, skill patches as the cycle's only output

MCA preconditions (all three must hold)

A cycle qualifies as MCA only when γ can answer yes to all of:

1. Design committed at a stable path (not in the issue body) — docs/{tier}/{bundle}/{X.Y.Z}/DESIGN.md, an architecture doc, or a converged proposal. The path must resolve and the document must be the source of truth, not a draft.
2. Plan committed with explicit step ordering — docs/{tier}/{bundle}/{X.Y.Z}/PLAN.md or equivalent, listing the sequenced work items α will execute. The plan names what α does in what order, not just that α will do something.
3. Both stable — neither will be edited during the cycle. If a step would require revising design or plan, the cycle is not MCA.

If any of the three fails, γ declares the cycle as explore or design-and-build and (where applicable) stages a separate design cycle first.

MCA cycle citation

When mode = MCA, the issue's Source of truth table MUST cite the design path and the plan path:

| Claim / surface | Canonical source | Status |
|---|---|---|
| Design | `docs/.../DESIGN.md` | Shipped |
| Plan | `docs/.../PLAN.md` | Shipped |

Without these rows, the mode is mis-labeled — γ either re-declares the mode or stages the missing artifact.

Failure mode when mis-labeled MCA

α re-derives the plan from the issue body, which inflates context load and review pressure. The supercycle in usurobor/tsc master #23 produced direct evidence:

• Cycles where MCA discipline was honored (design + plan stable, cited) ran in 1–2 review rounds
• Cycles where the design surface was ambiguous (no stable plan, α re-deriving) ran in 3 review rounds

Mis-labeling MCA is not free — it costs α context and β review patience.

---

Cycle scope sizing

γ sizes a cycle at scoping time — not after dispatch. The sizing decision appears explicitly in the issue body and is verified at handoff.

Soft AC-count guideline

Band	AC count	Signal
Small	1–4	Single-focus; artifact-class collapse optional (see cdd/CDD.md §1.2)
Typical	5–7	Standard cycle; monitor round-count target (≤2 code, ≤1 docs)
At-edge	8–10	Allowed; requires five-factor check and written justification if kept whole
Split-or-justify	≥11	Must split into master+subs or provide written justification

The guideline is soft — γ's judgment governs. The heuristic forces the judgment to be visible.

Five-factor split-decision heuristic

For any cycle at the at-edge (8–10) or split-or-justify (≥11) band, γ applies:

Factor	Question	Splitting signal
(a) New code surface	How many new modules, packages, or runtime contracts does this introduce?	≥2 new modules → split
(b) Cross-module breadth	How many existing modules are touched in non-trivial ways?	≥3 modules touched → split
(c) Lifecycle span	Does the issue span multiple lifecycle phases (design → code → docs → infra) in ways that would serialize α's context?	Phases can't overlap → split
(d) MCA-precondition stability	Would mid-cycle design discovery force re-scoping?	Design not yet stable → explore or design-and-build cycle first
(e) Independent shippability of AC groups	Can any AC subset be shipped and used independently of the rest?	Yes → subs are the right shape

A "yes" on any single factor is a signal; a "yes" on two or more factors is a strong split indicator.

Master+subs pattern

When γ decides to split, the master+subs pattern applies:

1. Independent shippability of subs — each sub-issue is executable, verifiable, and shippable on its own. A chain where sub B blocks on sub A's merge is an anti-pattern; avoid it.
2. Master cites subs via the repo's native sub-issue mechanism (cnos: sub-issue field; cnos-tsc: mcp__github__sub_issue_write).
3. Master closes when all subs are closed, or any deferred sub is explicitly named as tracked debt in the master's closure condition.

Empirical anchor

Evidence from usurobor/tsc#23 (cnos-tsc supercycle, cycles 24–29):

• Cycle 25 (12 ACs, 2 rounds): ran at the at-edge; α's 20-minute reading phase before first commit was operator-ambiguous ("stuck vs thinking"). Smaller issues converge faster and produce a clearer signal.
• Cycle 24 (7 ACs, 3 rounds): same AC count as a "typical" cycle but touched 3+ modules with new runtime contracts. AC count alone did not predict round count — factors (a) and (b) were the load driver.
• Cycle 26 (6 ACs, 1 round) vs cycle 29 (6 ACs, 2 rounds): identical AC count, different difficulty. Factor (b) diverged — cycle 29 touched a cross-cutting surface that cycle 26 did not.

The five-factor heuristic encodes what AC count alone cannot capture.

---

When to load each subskill

Load subskills as the issue shape requires:

• issue/labels — when selecting or reviewing kind, priority, or surface labels for the issue title and header.
• issue/contract — when writing problem, impact, status truth, source of truth, scope, non-goals, skills, constraints, related artifacts, implementation guidance, or closure condition.
• issue/proof — when writing acceptance criteria, proof plan, or oracle/positive/negative cases.
• issue/constraints — when writing constraint strata, exceptions ledger, path resolution rules, or cross-surface projection lists.

For a simple issue with few ACs, loading issue/labels and issue/contract may be sufficient. For complex tooling/CI/runtime issues, load all four.

---

Minimal output pattern

# Title
Labels: <kind>, <priority>[, surface…]

Priority: <P0–P3> — <one-line rationale>
Status: <one-line summary>

## Problem

What exists:
What is expected:
Where they diverge:

## Impact

## Status truth

## Source of truth

| Claim / surface | Canonical source | Status | Notes |
|---|---|---|---|

## Scope

In scope:
Out of scope:
Deferred:

## Cycle scope sizing

| Factor | Reading | Splitting signal? |
|---|---|---|
| (a) New code surface | | |
| (b) Cross-module breadth | | |
| (c) Lifecycle span | | |
| (d) MCA preconditions | | |
| (e) Independent shippability | | |

Decision: keep whole / split into master+subs — <one-line justification>

## Acceptance criteria

### AC1: …

Invariant:
Oracle:
Positive:
Negative:
Surface:

## Proof plan

Invariant:
Surface:
Oracle:
Positive case:
Negative case:
Operator-visible projection:
Known gap:

## Skills to load

Tier 3:
- …

Why:
- …

## Active design constraints

## Related artifacts

## Source Proposal

- Source:
- Source commit:
- Disposition:
- Delta:

Optional; include only when this target issue comes from a cross-repo source proposal.

## Non-goals

## Success / closure condition

This issue is closeable when:
- all ACs are met;
- the proof plan passes;
- non-goals remain unviolated;
- known gaps are either resolved or explicitly carried as named debt.

For small issues, compress the shape but preserve: problem, impact, ACs, non-goals (if substantial), source of truth, and proof surface.

---

Closure rule

An issue is closed when:

• every AC maps to evidence in the branch diff;
• the proof plan oracle produces a passing result;
• no non-goal noun appears in the diff;
• known gaps are named explicitly in self-coherence.md.

---

Handoff checklist

Before filing or dispatching:

• Problem states exists / expected / divergence.
• Impact says who cares and what is blocked.
• Status truth is explicit (no draft behavior described as shipped).
• Source-of-truth paths resolve.
• Scope and non-goals do not contradict ACs.
• Contradictions between issue sections are resolved explicitly.
• Hard gates do not appear in exception examples.
• ACs are numbered and independently testable.
• Proof plan has oracle, positive case, negative case.
• New surfaces include operator-visible projections.
• CI additions include notification/status implications.
• Related artifacts include canonical docs with exact paths.
• If the target issue comes from a source proposal, ## Source Proposal names source path, source commit when known, disposition, and delta when modified.
• Examples obey the rules they are demonstrating.
• Known gaps are named honestly.
• Labels: exactly one kind label and one priority label (load issue/labels).
• Mode declared: MCA / explore / design-and-build / docs-only.
• If MCA: design and plan paths cited in source-of-truth table; both stable.
• Cycle scope-sizing decision recorded; if at-edge (8–10) or above (≥11), justification or master+subs pointer present.

---

External kata

Practice and evaluation for this issue skill live in:

src/packages/cnos.cdd.kata/katas/M5-issue-authoring/

That kata exercises status-truth split, source-of-truth alignment, constraint strata, AC negative space, proof-plan oracle, and non-goal discipline.