OpenParable
Skip to content
← Back to skills

To Issues

Productivity
to-issues

To Issues is an Agent Skill for productivity published in the DanMcInerney/architect-loop repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when decomposing a hardened spec into tracker issues: cutting tracer-bullet vertical slices through every layer, ordering structural work first with blocking edges, maximizing the disjoint parallel frontier, publishing producer/consumer interface contracts, and attaching a compact change-skeleton to each issue. Invoked only from an explicit architect dispatch — by the harden strategist subagent in `/architect`, or directly by the orchestrator in `/architect-fast` — after the spec is written; never left to description-trigger discovery.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/DanMcInerney/architect-loop/blob/HEAD/skills/to-issues/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/to-issues, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

To Issues

Turn the hardened spec into dispatch-ready issues under the tracking issue. The spec already settles the whole plan — this stage does not quiz the human; a hard stop or an oddity escalation is the only thing that opens a question here.

1. Read before you cut

Load the spec, then hold the codebase-design vocabulary (skills/codebase-design/SKILL.md) exactly: module, interface, implementation, seam, adapter, depth, leverage, locality for design; run, tracking issue, issue, slice, frozen check, check-runner, strategist, builder, orchestrator, factory branch, worktree, job report, verdict, ruling, digest, hard stop for the factory. Never substitute component/service/boundary/API for module/interface, or task/ticket for issue — that drift is a defect, not a style choice.

Look for prefactoring while you read: make the change easy, then make the easy change.

2. Structural before behavioral

Structural (prefactoring) issues land first, with blocking edges into the behavioral issues they unblock. A structural issue's checks prove existing behavior stays green — it changes shape, not outcome.

Oddity rule while scoping: a local wart gets a local patch note, not its own issue. A variation that recurs gets a structural issue blocking the behavioral one. One adapter is a hypothetical seam; two adapters make it real — write the structural issue. Three failed fixes on the same point means stop and escalate the design question instead of cutting a fourth fix.

3. Cut tracer-bullet vertical slices

Each issue is a tracer-bullet vertical slice: a narrow but complete path through every layer the change touches, demoable or verifiable on its own — never a horizontal slice of one layer.

Avoid specific file paths or code snippets in issue prose — they go stale fast. Exception: a prototype snippet that encodes a decision more precisely than prose can (state machine, schema, type shape); trim to the decision-rich parts.

4. Maximize the disjoint parallel frontier

Compute readiness from each issue's file-touch set, not only its blocking edges. Issues dispatched in the same wave share no files, migrations, lockfiles, generated artifacts, config, schemas, or other mutable runtime state. A shared-file collision is a decomposition failure — split or resequence; never hand-merge it later.

5. Interface contracts, not future-code citations

An issue that produces a surface another issue consumes publishes an interface contract block: names, parameters, return types, and behavior. Consumer issues cite that block; they never cite the producer's not-yet-written implementation.

6. Body shape

Every issue carries: acceptance criteria; MAY TOUCH / MUST NOT TOUCH file sets; its check path; its raw job-report path; blocked-by and parent edges; a compact change-skeleton (≤30 lines — files, signatures, data flow, invariants; a contract, not a line mandate). Close every issue body with the run marker comment: <!-- architect-run: <run> -->.

7. Draft in publish order; the orchestrator publishes

Write one draft file per issue at docs/runs/<run>/issues/<NN>-<slice>.md (a local run artifact), NN numbered in publish order: structural issues first, blockers before the issues that cite them. Name blocked-by and parent edges by slice name — real issue numbers do not exist yet; the orchestrator maps slice names to issue numbers as it publishes in NN order, so every blocked-by resolves to a real, already-open issue and never a forward reference. Do not post to the tracker yourself — publishing sub-issues, edges, and claims are orchestrator actions (skills/architect/dispatch.md ## Issue conventions). When the orchestrator runs this skill directly (/architect-fast), it publishes the drafts itself in the same order.

Done when every slice in the plan has a draft file — structural-first, frontier-maxed — whose order publishes with no forward references. End your reply with one line: ISSUE DRAFTS: <count> at docs/runs/<run>/issues/.