GitHub Issue
- An issue is picked up days or weeks after it is written, and the tree changes many times in between.
- The Agent that picks it up reads the tree in seconds. It cannot recover the Problem, the intent, or the impact from any tree.
- So the issue carries the WHO, the WHY, and the WHAT. The Agent that executes it owns the HOW.
1. Understand the Problem, then stop researching
Take the Problem from the Architect's own words. Read only far enough to confirm the Problem is real and to name the systems it crosses.
Stop reading code once you can name the systems involved
The systems and their interaction are what the issue carries. Reading further produces detail that goes stale before the issue is picked up.
Never describe unread code
Describe only code already read in this Task.
2. Write the body from the Template
Every slot is filled with what stays true as the tree changes.
State the Problem as a behavior, never as the change to make
The Problem is what the system does today and why that is wrong. A body that opens with the change hides the Problem, so the executing Agent cannot find a better path. Example: "Two Agents editing the same session file overwrite each other, so the later write loses the earlier Agent's Task." Never: "Add a lock to session_state.py".
Name systems by their durable name, never by a position inside a file
A system's durable name is the module, the command, the Skill, or the Hook event. Line numbers, line ranges, function bodies, and call order are wrong by the time the Agent starts.
Never: session_state.py:594, "the loop at the top of the function", or a pasted code block.
Never: the config file, the auth module, or the usual place.
Keep exact text the Architect fixed
A name, an error message, a command, or a contract the Architect decided is durable. Write it exactly.
Record every rejected option with its reason
An unrecorded rejection gets rediscovered and re-chosen weeks later. One line each.
Write each acceptance criterion as an outcome
A criterion states what is true for the User or the system when the work is done, and stays true however the Agent builds it. Never: a criterion naming a file, a function, or a test name.
Inline every source the implementing Agent needs
The body never points back to conversation Context, external files, Plans, or Shaping. It carries the needed content itself.
Never: see above, as discussed, see the shaping doc, or see the Plan file.
Template:
## Problem
<what the system does today, who it hurts, what it costs>
## Why this matters
<the intent behind fixing it, in the Architect's words>
## Systems involved
<the systems by durable name, and how they interact today>
## Constraints
<boundaries that hold, options already rejected and why, Capabilities that must not regress>
## Done when
<outcome criteria>
3. Audit the body for durability
Ask one question of every sentence: is this still true if the tree changes ten times before the Agent starts?
IF a sentence fails that test:
Raise it to the durable level, or cut it
A line number becomes the system that owns the behavior. A code block becomes the interaction it showed. A step-by-step HOW becomes the constraint that HOW was serving.
IF a Template slot is empty:
Fill the slot before creating or updating the issue
Do not run gh issue create or gh issue edit until every slot is filled.
4. Create the issue
Run gh issue create, always pass --assignee @me, pass --repo <owner/repo> or --label when specified, then report the issue URL.
Template:
gh issue create --assignee @me --title "<title>" --body "$(cat <<'EOF'
<body>
EOF
)"
5. Update the issue
Use gh issue edit when the body, title, labels, or state changes. Every edit gets a gh issue comment stating WHAT changed and WHY. Body rewrites go through step 3 before editing.
Add a change comment for every edit
The comment makes the changed issue self-contained for the next Agent.
Template:
gh issue edit <number> --body "$(cat <<'EOF'
<updated body>
EOF
)"
gh issue comment <number> --body "$(cat <<'EOF'
## Changes
- <WHAT changed>
WHY: <WHY these changes were necessary>
EOF
)"
gh issue close <number> --comment "Resolved: <reason>"