GitHub Issues are not your thinking space. They are execution contracts.
Your Obsidian scratchpad can be messy. Your Discord thread can be conversational. Your GitHub Issue should be shaped enough that a human or agent can pick it up, make one bounded slice of progress, verify it, and report back.
Outcome for this lesson
By the end, you should have one agent-ready GitHub Issue created from a routed input or scratchpad item.
The issue should include:
- goal;
- context;
- scope;
- out of scope;
- acceptance criteria;
- source links;
- verification plan;
- reporting destination.
What makes an issue agent-ready
An agent-ready issue answers four questions:
- What should change?
- Why does it matter?
- What is explicitly out of scope?
- How will we know it is done?
If the issue cannot answer those, the agent will fill gaps with guesses.
Step 1: start from a scratchpad, not a vibe
Good issues usually come from a durable source:
- thread scratchpad;
- project note;
- research note;
- customer quote;
- bug report;
- content plan;
- routing decision.
Do not create the issue from memory alone if the work has context. Link the source.
Step 2: write the goal as an outcome
Weak goal:
Better goal:
The goal should describe the user-facing or operator-facing result, not just the activity.
Step 3: define scope and out of scope
Scope prevents wandering.
Out of scope is not bureaucracy. It is how you keep one slice reviewable.
Step 4: make acceptance criteria testable
Acceptance criteria should be checkable without mind-reading.
Weak:
Better:
Step 5: require receipts
A finished issue should produce proof.
For code or content work, receipts may include:
- changed file paths;
- branch name;
- commit SHA;
- PR URL;
- test command and result;
- preview URL;
- production URL;
- screenshot;
- final scratchpad update.
The issue should say what kind of receipt is expected before the work begins.
Copy this GitHub Agent Issue template
Step 6: create one issue
Take one routed input from the previous lesson and promote it into a GitHub Issue only if it is ready.
If it is not ready, do not force it. Move it back to a scratchpad and add the missing question.
Verification checkpoint
You are done when your issue:
- links to its source scratchpad or note;
- has a clear outcome;
- has scope and out-of-scope boundaries;
- includes concrete acceptance criteria;
- names the verification receipts expected at the end;
- could be handed to another person without a long verbal explanation.
Next lesson
The issue is only the handoff. Next, close the loop: input, scratchpad, issue, implementation, verification, and final status back to the original thread.