Start from the bug, investigate the codebase to locate the root cause, then write a detailed agent brief report to guide an AFK agent through the fix. Think of yourself as a detective searching for clues in the codebase.
Process
1. Get context
Read the ticket corresponding to the issue. Read the CONTEXT.mdin the project root (if it exists, have /setup-matt-pocock-skills confirm it), and understand the project architecture, domain terminology, and any relevant ADRs under docs/adr/ .
2. Read the source code
Trace the bug — start from the behavior the user sees, follow the code path, until you find the root cause. The goal is to map it to aspecific high-level moduleand thelogicwithin it that is going wrong. Specifically:
- Start from the symptoms reported in the issue
- Trace back along the call path
- Identify which piece of logic produces the incorrect behavior
- If needed, run tests and code checks to verify your judgment
- Check git log to find recent changes to the relevant area (
git log --oneline --all -- <path>), and incorporate the clues into your conclusion
3. Write the report
Write a substantive report covering the following:
- Findings(why the problem occurs)
- Cause(what the root cause is in the code)
- Fix(how it should be corrected)
Cite specific function names, types, and domain terminology, but do not write file paths or line numbers — these go stale easily.
Then use this report to update the issue (as a comment), and attach a complete agent brief, so that an AFK agent can take over the fix.
Guiding principles
Be a code detective, not just a paraphraser
Do not merely restate the contents of the issue report. Trace the code, form your own judgment, and then give an opinion. You should be able to say: "I followed the call chain, and here is what happened, why it happened, and what needs to change."
Cite specific domain terminology
If the project's CONTEXT.md calls a certain module a "resolver chain", then use that term too. Using the codebase's own vocabulary makes it easier for the agent to act on your judgment.
Write an agent brief that others can use directly
Your report is only the groundwork; what matters is the agent brief — an AFK agent should be able to complete the fix strictly based on the brief, without needing to go back and read the context in the issue discussion. For the specific format, see AGENT-BRIEF.md。