4.9 KiB
| name | description | argument-hint | invocation |
|---|---|---|---|
| understand | Research and understand a module, folder, or problem before implementing, capturing what you learn as local notes. Use before starting a complex task or to deepen understanding of an area. Optional argument is a module path/name and/or a Jira issue ID (e.g. ABC-123). | [module-or-topic] [JIRA-ID] | user |
Understand
You research a module, folder, or problem so the developer starts implementation with a clear
picture, and you capture what is learned as local notes for reuse. You do the research and reasoning
yourself; the note-reader and note-taker agents own all note I/O - you never read or write the
note directly.
The goal is understanding, not a deliverable document. Keep the session interactive and let the developer steer what matters.
This skill produces understanding and notes - it does not implement the change. When the notes capture the picture, stop and hand back to the developer. Beginning the implementation is a separate, explicit decision they make; never slide from understanding into editing code.
This skill writes files, so it cannot run in plan mode. The notes are its whole output, and plan
mode blocks every write - including the note-taker agent's. If plan mode is active, say so up
front and ask the developer to exit it (or approve the plan) before you research; never take the
developer through the whole session only to finish with nothing written.
Write notes as you go, not at the end. The moment an insight crystallizes - during research,
cross-referencing, or the interview - record it via note-taker so the developer watches the
domain. and task. notes grow. Never batch note-taking into a single final step: a session that
reaches its conclusion with no notes written has failed its one job.
Argument Parsing
Arguments after /understand (both optional, order does not matter):
- An identifier matching
[A-Z]+-\d+is a Jira issue ID. - Anything else is the target: a module path/name, folder, or topic.
If no target is given, ask the developer what to focus on before proceeding.
Steps
1. Recall existing context
Before researching, dispatch the note-reader agent to pull any notes that already exist for the
target. Use what it returns to seed your understanding - do not re-derive what is already recorded.
Also read any notes the developer references explicitly.
Target: {module / topic / problem the developer named}
Looking for: existing domain and task notes relevant to this work.
2. Research the code
Explore the target with your built-in tools. If the surface is large enough that reading it inline would flood context, spawn the built-in Explore agent and work from its findings instead.
3. Fetch task material
If a Jira ID was given (or embedded in the branch name, [A-Z]+-\d+), fetch it via the connected
Atlassian MCP - title, description, type. If the fetch fails, note it in one line and continue.
Gather the developer's manual notes and any observed symptoms from the conversation.
4. Cross-reference and draft
Check the developer's stated assumptions against the actual code and surface contradictions explicitly, e.g. "your code cancels the whole Order, but you said partial cancellation is possible - which is right?" Present a condensed understanding of how the area works and where the task fits.
As soon as the picture is solid enough to be useful, dispatch note-taker to file a first pass
(see step 6). Do not wait for the interview to finish - the note should already exist and then grow.
5. Optional interview
Offer a gap-filling interview - Jira gaps, constraints, decisions, edge cases - and run it only if the developer opts in. Walk one branch of the decision tree at a time, and for each question give your recommended answer. If a question can be answered from the code, answer it from the code.
As each question resolves, update the relevant note immediately rather than saving them for the end.
6. Persist (throughout, not only here)
Record insights the moment they crystallize during steps 2-5 - not batched into this step. Each time,
dispatch note-taker:
- Durable, canonical architecture facts ->
domain:<topic>(kept crisp by the agent). - Task-specific context - Jira, symptoms, scratch findings ->
task:<name>.
When the domain/task split is ambiguous, confirm it with the developer before filing. Before you finish, do a final sweep so every insight from the session is captured in a note.
Target: domain:{topic} # or task:{name}
Insight:
{the crisp fact(s) to record, or the task context to append}
7. Report
Tell the developer which notes were written or updated, using the one-line confirmations note-taker
returned. Do not paste the full note content back.
Then stop. Do not begin implementing the change - if the developer wants to proceed to implementation, that is a new, separate instruction from them.
