# Issue intake procedure

Canonical owner for the routed `issue_intake` procedure behind the public `dev-loop` façade: preflight, normalization, async refinement, epic decomposition, and Copilot handoff.

Use it with:
- [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md)
- [Public Dev Loop Contract](./public-dev-loop-contract.md), owner of the `FACADE-*` rules cited below
- [Retrospective Checkpoint Contract](./retrospective-checkpoint-contract.md) when the current step depends on async start/resume/status or retrospective enforcement
- [Stop Conditions](./stop-conditions.md), owner of `STOP-INITIAL-COPILOT-001` and the other strategy-wide stop/wait rules
- [Merge Preconditions](./merge-preconditions.md), the merge gate this procedure defers to

Use this issue-refinement specialist procedure for issue-first routed work before entering the shared post-PR loop.

## New-idea safety layer (default contract in this repo)

<!-- rule: INTAKE-NEW-IDEA-SAFETY -->
For **all new ideas** that are not already anchored to an existing issue (including abstract ideas such as plain-language requests without an issue number or plan-doc path), the procedure MUST apply this intake contract before any GitHub mutation:

- procedure owns classification; human operator gates all mutations
- run classification in fresh context by default
- run classification asynchronously when practical
- run async fan-out / fan-in proposal generation by default when practical
- emit a proposal artifact before any GitHub state-changing mutation, including create/edit/retitle/collapse/link operations
- default to create-new over overwrite/update when a new tracked artifact is justified
- do not repurpose/retitle/collapse/overwrite an existing issue unless that exact mutation is explicitly proposed and explicitly approved
- after approval, run a second async mutation pass (dispatched via the procedure) instead of mutating directly from inherited context
- verify post-mutation artifact state and record what actually changed

**Quick-capture exemption:** the board quick-capture enqueue freeform path (`/dev-loops:loop-enqueue`, or `/loop-enqueue` in the dev-loops repo itself) MAY defer the up-front proposal artifact, the async classification pass, the async fan-out/fan-in proposal generation, and the second async mutation pass. Its inline human-approved confirm→create→grill steps stand in for them. The human-gated-mutation and create-new-only safeties still apply: it always creates a new issue and never repurposes/overwrites an existing one.

Deterministic intake + mutation-gate state machine:

```text
idea_received
  -> fresh_context_started
  -> fanout_started
  -> fanin_complete
  -> artifact_scan_complete
  -> classified
  -> proposal_emitted
  -> awaiting_user_approval
  -> ready_for_mutation
  -> mutation_executed
  -> mutation_verified
  -> done

stop states:
- stopped_overlap_needs_decision
- stopped_low_confidence
- stopped_explicit_reject
```

Proposal artifact contract:
- human-readable Markdown proposal
- machine-readable JSON snapshot
- write temporary artifacts under `Proposal` (`tmp/new-idea-intake/<run-id>/proposal.md`) and `tmp/new-idea-intake/<run-id>/proposal.json`

<!-- rule: INTAKE-STOP-STATES -->
If the Phase 1 preflight verdict is `pause_for_clarification`, the procedure MUST stop and ask.
If the intake state machine stops at `stopped_overlap_needs_decision` or `stopped_low_confidence`, the procedure MUST stop and ask.
If the intake state machine stops at `stopped_explicit_reject`, the procedure MUST stop and record that the proposal was rejected; it MUST NOT mutate GitHub.

After approval, the separate async mutation pass consumes the approved proposal. It must emit a concise post-mutation verification artifact that records what actually changed and the verified issue/artifact state.

## Unattended issue-first execution and automatic re-entry

When the user explicitly authorizes unattended execution for a specific issue/PR scope, continue through the normal loop mutations for that scope without stopping at every intermediate phase boundary.

Under that unattended execution contract:
- automatically detect the current lifecycle entrypoint from existing GitHub state
- use the deterministic helper/state-machine surface as the authority for current-state routing and next-step selection
- if local facts, GitHub facts, and helper/state-machine output do not agree, or the state is materially unclear, contradictory, off-trail, or not cleanly covered, stop and ask for human direction rather than guessing
- a pre-existing PR is not a stop-by-default condition
- If a PR already exists, classify the post-assignment seam before follow-up
- `waiting_for_initial_copilot_implementation`: keep waiting
- `linked_pr_ready_for_followup`: route to the existing PR follow-up path immediately; resume from that PR
- when routing leaves bootstrap wait for `linked_pr_ready_for_followup`, follow [FACADE-BOOTSTRAP-ISOLATED-WORKTREE-CONTINUATION](public-dev-loop-contract.md): re-enter the same PR follow-up from a safe isolated checkout/worktree instead of stopping solely because local isolation is required
- When the draft PR appears, classify whether it is still the bootstrap-only Copilot draft before entering normal follow-up
- if a child async run exits while the deterministic state is still non-terminal (for example `waiting_for_copilot_review`), automatically resume/restart follow-up when continuation is feasible instead of requiring manual operator restart
- continue unattended until the human approval checkpoint unless a genuine stop condition is reached
- stop for a human approval decision by default
- after approval, report `waiting_for_merge_authorization` and stop again unless merge has been explicitly authorized
- this does **not** imply unattended merge by default

Issue-first shorthand such as `auto dev loop on issue <n>` should preserve this same stop boundary and human approval checkpoint default.

## Phase 1 — Preflight intake

Before any automation, answer these questions:
1. smallest executable work item
2. existing issue check
3. scope clarity
4. acceptance criteria
5. verification path
6. active PR check

Accepted input types:
- GitHub issue number or URL
- plan-doc path
- abstract roadmap idea

Preflight verdicts:
- `proceed`
- `proceed_with_assumptions`
- `pause_for_clarification`

## Phase 2 — Input normalization

### From a GitHub issue number or URL

- if the input is a full GitHub issue URL, parse `<owner/name>` and `<number>`
- fetch with `node scripts/github/view-issue.mjs --repo <owner/name> --issue <number> --json number,title,body,state,labels,assignees,milestone`
- If the issue is closed, stop for a user decision before proceeding
- detect an existing linked PR with the deterministic linked-PR helper:
  `node <resolved-skill-scripts>/github/detect-linked-issue-pr.mjs --repo <resolved-repo> --issue <number>`
- treat the helper output as authoritative for linked-PR detection/selection
- <!-- rule: INTAKE-LINKED-PR-HELPER-DELEGATION --> `INTAKE-LINKED-PR-HELPER-DELEGATION`: Agents MUST NOT re-implement linked-event query behavior, pagination, repo filtering, or tie-break logic, and MUST NOT rely only on PR title/body containing a literal issue number.
- treat an open linked PR as the active implementation for this issue
- once an open linked PR exists, attach follow-up work to it per `FACADE-LINKED-PR-SINGLE-ARTIFACT` (owned in [Public Dev Loop Contract](public-dev-loop-contract.md)) for the `issue_intake` strategy
- follow-up-capture rule: a follow-up discovered while working a PR or loop goes as a comment on the originating issue, in the PR body, or as a comment on an existing issue or epic. A standalone issue is filed only under `MAIN-AGENT-FILING-BLOCKER-ONLY` in [Main Agent Contract](./main-agent-contract.md#filing-from-runner-findings). See [Sub-Issue Tree Contract](./sub-issue-tree-contract.md).
- if a PR already exists, classify bootstrap-wait versus follow-up:
  `node <resolved-skill-scripts>/loop/detect-initial-copilot-pr-state.mjs --repo <resolved-repo> --issue <number>`
- `waiting_for_initial_copilot_implementation`: keep waiting; in durable-auto mode use:
  ```sh
  node <resolved-skill-scripts>/loop/watch-initial-copilot-pr.mjs --repo <resolved-repo> --issue <number>
  ```
  - durable-auto ownership of this seam (the dedicated watcher + its default 1-hour watch budget) is owned by [FACADE-BOOTSTRAP-WATCH-ROUTE](public-dev-loop-contract.md); this procedure does not restate that rule
  - quiet/no-activity watch observations alone are non-terminal
  - `ready_for_followup`: linked PR has become substantive; resume from that PR
  - `timed_out` with `outcome: "pending"`: the per-call cap was reached and the watch budget is not exhausted; run the returned `reissue` unchanged per `GATE-EXEC-BOUNDED-WAIT-CAP`, and never re-run `watch-initial` with a fresh budget
  - `timed_out`: observational first; refresh authoritative state
  - if refreshed state is still `waiting_for_initial_copilot_implementation`, remain attached to the same durable wait seam and continue waiting
  - <!-- rule: INTAKE-TIMEOUT-ROUTE-ON-SEAM-EXIT --> `INTAKE-TIMEOUT-ROUTE-ON-SEAM-EXIT`: if the refreshed state exits this seam, route based on that refreshed state instead of surfacing timeout attention
  - when the refreshed state is `linked_pr_ready_for_followup`, re-enter normal PR follow-up per [FACADE-BOOTSTRAP-ISOLATED-WORKTREE-CONTINUATION](public-dev-loop-contract.md): if the follow-up handoff carries `conductorRouting.handoffEnvelope.requiresLocalIsolation=true`, perform the expected isolated-checkout/worktree handoff and continue
  - <!-- rule: INTAKE-TIMEOUT-SURFACE-BUDGET-EXHAUSTED --> `INTAKE-TIMEOUT-SURFACE-BUDGET-EXHAUSTED`: only surface timeout attention when the seam's durable watch budget is actually exhausted
  - for explicit inspect/status requests, report the still-waiting state and exit normally
- carry that resolved repo slug through every later GitHub issue/PR command
- before invoking `resolve-dev-loop-startup.mjs --issue <number>` for local implementation on this directly-targeted issue, claim ownership by adding `--claim` to that startup call (`loop startup --issue <number> --claim`; it assigns the viewer only when the issue is unassigned, and only on the user's explicit start or continue request for this exact issue). The resolver's single-contributor ownership gate fails closed on a foreign or unclaimed assignee — see [Public Dev Loop Contract](public-dev-loop-contract.md#single-contributor-ownership-gate-resolve-dev-loop-startup)

### From a plan-doc path

- <!-- rule: INTAKE-REPO-SLUG-RESOLVE-FIRST --> `INTAKE-REPO-SLUG-RESOLVE-FIRST`: Resolve the target repository slug for this work item before any GitHub search or mutation
- default to the current repository slug
- if the plan-doc reference explicitly points at another GitHub repository, resolve `<resolved-repo>` first
- search existing issues with:
  ```sh
  gh issue list --repo <resolved-repo> --state all --search "<title keywords>"
  ```
- If a matching issue exists:
  - if the matching issue is closed, stop for a user decision before proceeding
  - if a PR already exists, classify bootstrap-wait versus follow-up
- if a governing plan doc or roadmap section actually applies, follow the plan-doc normalization path above

### From an abstract idea

- otherwise search existing issues directly
- if a matching issue exists, follow the issue-number/URL normalization path
- resolve `<resolved-repo>` for this work item using the same rule as the plan-doc path

## Phase 3 — Async issue refinement

Before updating or assigning the issue, refine it asynchronously when practical. Keep issue refinement separate from the phase-scoped refiner used by the local implementation workflow. Use the `refiner` agent for this review-only issue-refinement chain, including the consolidation/fan-in step; do not route those comparison/synthesis steps through `dev-loop` + `local_implementation` (the strategy loaded by `skills/local-implementation`).

When issue refinement would benefit from structural/slop discovery and the likely code/doc surface is knowable, run the bounded audit first.
- write the issue-refinement audit artifact to `tmp/issues/issue-<number>/audit/refinement-audit-summary.json`
- use the same audit artifact shape as local phase refinement
- keep the audit bounded to the named files/areas for this issue; do not widen into a full-repo scan
- pass a concise audit summary into refiner fan-out and fan-in
- require the issue-refinement write-up to translate audit findings into scope, AC/DoD, risks, and explicit non-goals without silently broadening the issue

## Phase 3b — Epic decomposition with GitHub sub-issue trees

When an umbrella/epic issue must be decomposed into bounded, independently closable child slices, use **real GitHub sub-issue trees** as the default durable output. Prefer real sub-issue linkage over parent-body checklists. The parent issue body should stay lean: keep scope, acceptance criteria and non-goals there, under `SUBISSUE-LEAN-BODY-NO-DUPLICATE`.

Follow the "Default decomposition flow" in [Sub-Issue Tree Contract](./sub-issue-tree-contract.md), which owns the full `manage-sub-issues.mjs` contract and `SUBISSUE-NO-ADHOC-BYPASS`. Create children with `gh issue create --repo <resolved-repo> --assignee @me`, then:

```sh
node <resolved-skill-scripts>/github/manage-sub-issues.mjs add \
  --repo <resolved-repo> --issue <parent-number> --child <child-number>
node <resolved-skill-scripts>/github/manage-sub-issues.mjs reorder \
  --repo <resolved-repo> --issue <parent-number> --order <n1,n2,...>
node <resolved-skill-scripts>/github/manage-sub-issues.mjs verify \
  --repo <resolved-repo> --issue <parent-number> --expected <n1,n2,...> [--ordered]
node <resolved-skill-scripts>/github/manage-sub-issues.mjs list \
  --repo <resolved-repo> --issue <parent-number>
```

The [Epic Tree Refinement Procedure](./epic-tree-refinement-procedure.md) owns scope alignment, AC/DoD contracts and delegation-boundary refinement of an existing tree across all levels. This procedure creates the tree.

## Phase 4 — Copilot handoff and bootstrap wait

Before updating the GitHub issue body, show the diff and get explicit confirmation. Then use:
```sh
node <dev-loops-package-root>/cli/index.mjs issue edit --repo <resolved-repo> --issue <number> --body-file <updated-body-file>
node <dev-loops-package-root>/cli/index.mjs issue edit --repo <resolved-repo> --issue <number> --add-assignee copilot-swe-agent
```
(source-repo fallback: `node scripts/github/edit-issue.mjs ...`)
Verify assignment with:
```sh
node scripts/github/view-issue.mjs --repo <resolved-repo> --issue <number> --json assignees
```

When the linked PR becomes substantive, keep the shared loop scoped to the resolved repo, for example:
```sh
node <resolved-skill-scripts>/loop/copilot-pr-handoff.mjs --repo <resolved-repo> --pr <number>
node <resolved-skill-scripts>/github/edit-pr.mjs --repo <resolved-repo> --pr <pr-number> --title "..." --body-file <body-file>
node <resolved-skill-scripts>/github/ready-for-review.mjs --repo <resolved-repo> --pr <pr-number>
node <resolved-skill-scripts>/github/detect-checkpoint-evidence.mjs --repo <resolved-repo> --pr <pr-number>
```

The ready transition uses `RAW-GH-PR-READY-BYPASS`'s mandatory wrapper in
[Anti-patterns](anti-patterns.md). Intake does not submit an approval review:
formal review submission belongs to `GATE-REVIEW-SUBMIT-MODES` in
[Gate Review Comment Contract](gate-review-comment-contract.md), including its
interactive-confirmation boundary. Gate verdicts remain COMMENT reviews.

The merge is gated by [Merge Preconditions](./merge-preconditions.md) through the sanctioned wrapper `scripts/github/merge-pr.mjs`; a raw `gh pr merge` is forbidden (`RAW-GH-PR-MERGE-BYPASS`). When `autonomy.humanMergeOnly: true` is set, the agent **never** merges; it reports merge-ready + gate evidence and hands off to a human. Only when **not** `humanMergeOnly` and merge is explicitly authorized may the agent run:
```sh
node scripts/github/merge-pr.mjs --repo <resolved-repo> --pr <pr-number> --human-approved-by <login>
```

Bootstrap-wait interpretation stays fail-closed: `timed_out` is observational first; refresh authoritative state and apply the Phase 2 still-waiting versus seam-exit branching above.
