Thinking

Issue kinds

Planned, backlog and hot Issues are three ways into the same task contract. They differ in who writes them, how long the body is and whether they declare relations.

Draft

Planned

Backlog

Hot

Issue body

About Issue kinds

Every task is a GitHub Issue. Vinaya has three kinds. They differ in why they exist, who writes them, how long their body is and whether they declare relations to other tasks.

All three lead into the same task contract. Each freezes into a brief, any kind can run in any execution mode, and every pull request lands on its Issue's parent branch (see Overview).

Kind	Why	Written by	Body	Relations	Guide
Planned	Part of a plan	The Planner, inside a tranche	Full: objectives, Surface, parts, checked facts, test plan	Dependencies, conflicts, order	Deploy medium work
Backlog	A stand-alone fix	The Planner, alone	Short: evidence pasted, every code fact as a checked fact, one or two objectives, pinned files, proof; no free text about code	None	Deploy backlog issues
Hot	Must change now	The Principal, at entry, with the readiness check done in person and recorded	Minimal: objective, pinned files, the facts read	None	Deploy hot issue now

A backlog Issue that turns out to need ordering is cut into a tranche instead. See Tranches and tasks.

How each kind flows

Step	Planned	Backlog	Hot
Marker	Label `vinaya/tranche:<slug>`	No `vinaya/tranche:*` label at all	Label `vinaya/hot`
Write	`vinaya issue create --label vinaya/tranche:<slug> --body-file <path>`	`vinaya issue create --body-file <path>` (no `--label`)	The same validated write, single-fix profile, plus a `Readiness:` line
Branch	`task/<tranche>/<n>`	`task/issue-<n>`	`task/issue-<n>`
Freeze	`vinaya task brief <tranche> <n>`	`vinaya task brief --issue <n>`	`vinaya hot start --issue <n>`
Run	`vinaya task run <tranche> <n> --agent …`	`vinaya task run --issue <n> --agent …`	The Principal and an agent edit live; `vinaya hot review --issue <n>`
Milestone	Attached automatically when an open Milestone names the slug	None	None

Body sections

Planned: the full form

The sections, in order:

Section	Grammar	Required
Title	Tranche slug, task number, an em dash, then the outcome title	Yes (`issue-title-grammar`)
`Tier:`	`0`, `1` or `3`	Yes
`Project:`	Registered project names, comma-separated, line-anchored	Yes (`project` builtin)
`Type:`	build, chore, docs, feat, fix, perf, refactor, revert, style or test	In the template
`## Objectives`	`O<n>. <sentence>`, numbered from `O1` with no gaps, one observable outcome each, no file path	Yes (`objectives` builtin, `issue-objectives-numbering`)
`## Documentation`	`- <source> — <mechanism it governs> (O<n>)` per source, or the single line `None`	Yes (`briefSections` builtin)
`## Planner's rationale`	Eight fields (below)	Yes (`issueRationale` builtin)
`## Premises`	One line per fact: `<path>` contains `<text>`, or after #<n>: `<path>` contains `<text>`	Optional. The only sanctioned place for a fact about code
`## Surface`	`in:` and `out:` folder-level glob lists. `*` means root-level files only	Yes (`briefSections`, `issue-surface-globs`)
`## Parts`	`Part <k> (O<n>[, O<m>]) — <outcome>`, outcomes and symbols only	Yes (`briefSections`, `issue-parts-coverage`)
`## Test plan`	A fenced command list, each `<command> → <expected observable>`, plus `[principal]` items; or `Test plan: unit-tests-only`	Yes (`briefSections`)
`## Stop conditions`	A bullet list	Yes (`briefSections`)
`## Origin`	Where the task came from	In the template

The eight rationale fields:

Boundary, with Pinned files: and Out:
Sizing
Project(s) + blast radius
Dependency rationale, bold-inline only
Traps to avoid
Suggested agent-class
Stop-and-escalate
Docs to keep coherent: paths, or no-doc-surface

No priority, estimate, points, status or pull request number may appear in the body. Vinaya's own repository configures the briefSchema.issue.sections builtins issueRationale, objectives, briefSections and project.

Backlog: the single-fix form

The same body, with three rationale fields left out: Sizing, Project(s) + blast radius, and Dependency rationale (written only if the fix does have an edge). Every other section is the same, with the same grammar.

The title takes the commit-type form Type(scope): Description, which is reused as the pull request title. An Issue gets this profile when it carries no task label.

Roles

Role	Planned	Backlog	Hot
Planner	Writes it, with the full readiness step	Writes it, with the full readiness step	—
Principal	Approves the tranche	Still an open decision	Writes it and performs the readiness step in person
Operator	May run `issue create --validate-only` on a draft	The same; never `issue create` (a planned rule)	Never enters hot mode

Gates

All three kinds pass the same Issue write: the five Issue checks and the briefSchema.issue builtins (see Thinking). Where they differ:

Gate	Planned	Backlog	Hot
`issue-milestone-attach`	Applies	Does not apply	Does not apply
Rationale check	Eight fields	Five fields (single fix)	Single-fix profile plus `Readiness:`
`dispatch-readiness`	Edges and Issue checked	`--issue` mode: the rationale as a single fix	`hot start` refuses while a driver is live or a pause is open
`first-push-dispatch`, `branch-topology`	Active	Dormant for `task/issue-<n>`	Dormant

Configuration

Key	Effect
`briefSchema.issue.sections`	The builtins every kind passes
`gateCutovers`	The Issue number from which the `objectives`, `briefSections` and Documentation rules apply
`principals`	Planned: who may enter hot mode. `hot start` reads it from the default branch and stops if that read fails

What gets logged

The same as Thinking: operation · completed per command, and gate · checked for failing checks.

What's next

Deploy backlog issues

Write and run a backlog Issue

Readiness and the frozen brief

How premises are checked

Hot mode

How a hot Issue runs

Ring 1 Issue checks

The five checks at Issue write