mirror of
https://github.com/woocommerce/woocommerce-paypal-payments.git
synced 2026-07-31 02:32:53 +08:00
105 lines
4.9 KiB
Markdown
105 lines
4.9 KiB
Markdown
---
|
|
name: understand
|
|
description: 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).
|
|
argument-hint: "[module-or-topic] [JIRA-ID]"
|
|
invocation: 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.
|
|
|
|
````payload-template
|
|
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.
|
|
|
|
````payload-template
|
|
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.
|
