dfa
GitHub引导用户逐步理解代码变更,通过发布包含关键决策点的交互式导览来解释修改内容。
触发场景
安装
npx skills add matheusfillipe/diffler --skill dfa -g -y
SKILL.md
Frontmatter
{
"name": "dfa",
"description": "Walk the human through a change in diffler, publish a walkthrough with one stop per real decision and answer their comments. Use when the user invokes \/dfa, says \"walk me through\", or asks the agent to present or explain what it changed."
}
Walk the human through $ARGUMENTS, or through everything you changed in
this review when $ARGUMENTS is empty:
- Call
review_status. It lists the repo'swalkthroughs. When one of them is about the change you are presenting, callget_walkthroughwith itsidand revise it, passing thatidtopublish_walkthrough; when the change is a different one, publish a new walkthrough without anid.review_statusnames therepo; if it is not the repository you mean, calllist_instances, thenuse_instancewith that repo, and start over. If the change spans another git repository, callopen_projectwith its path, then pass that project's name asprojectwhen publishing about it. A walkthrough is pinned to the commit it is published at, so publish it once the code it describes is the code checked out; once the branch has moved on, revise it so the stops point at the revision it is on now. - Read the diff with
get_diff. It shows whichever review is open right now: the working tree, or the commit, range, or PR you're reviewing.publish_walkthroughrecords that same review, so the walkthrough renders it too. A walkthrough works on a clean tree too: with nothing changed, publish over the working tree and anchor each stop to the file as it stands, to explain existing code. - Choose one stop per real decision, as few as the change needs: five is
common, ten is a lot, and more means the change wants splitting. Order
them as a reader should meet them. Each stop is a span (
path#symbolwhere a symbol exists,path:start-endotherwise), a title, and a body written as the section below says. A stop's span is the lines a marker would highlight, usually three to fifteen; a whole function only when the whole function is the decision. A barepathonly when the file itself is. A stop is a topic, not just a span: usenotesfor a second remark on another part of the same region, or a diagram beside the prose, each anchored in the stop's own file (path:lineorpath:start-end, or omitted to sit at the region's first line). Say each decision once. No overview stop that lists what the stops after it will say, and no closing stop that repeats them: the title is the overview, and a map of the whole change belongs in the summary below, not a stop. - Add a diagram when a shape beats a paragraph, in the kind that fits what
you are showing. Several fences in one body are fine, and a note can carry
one of its own when a different part of the region needs its own diagram.
-
A
mermaidflowchart for a branch, a state, or data moving through steps.subgraph id[Title]…endoutlines a group of nodes. -
A
mermaidsequenceDiagramfor who calls whom over time:participant A as Label,A->>B: textfor a call,B-->>A: textfor its reply,Note over A,B: text, andalt/else/endfor a branch.link B: label @ path#symbolmakes<cr>on any message toBopen that code. -
A
callstackfence for how a call path changed, as one tree: one frame per line, two spaces of indent per depth,+or-right before the label of an added or removed frame, and an optional@ path#symbolafter it that<cr>opens:handle_request @ src/http.rs#handle_request - legacy_auth + authenticate @ src/auth.rs#authenticate
-
- Put what you left out in
skipped. - Write a
summary: what the reader meets first. One short paragraph saying what the change does, plus one diagram of the simplest shape that explains it (step 4 says which kind fits), five to eight nodes, participants or frames, naming real files or functions. It never lists the stops and never repeats their titles: the stops are the detail, the summary is the shape. - Call
publish_walkthrough, read its receipts, fix a refusal and republish. When you revise, pass each surviving stop's and note'sidfromget_walkthroughso it keeps its comment and the thread hanging off it; one whose id you leave out is deleted. - Tell the human the walkthrough is on the status screen under Walkthroughs.
- Call
wait_for_feedbackin a loop: it carries feedback on every review, so check each comment'ssource. One startingwalkthrough-is a reply on a stop or note of that walkthrough, arriving as a reply on that comment; the id names which one. Answer in its thread withreply_comment. Revise the walkthrough withpublish_walkthroughwhen asked to change it, and keep waiting.
Every diffler tool call already shows in the human's status bar. Before a
stretch of work no tool call covers, such as reading the code around the
change or drafting the stops, call report_activity with a few words for it.
Write every stop like this
The human reads the title in a sidebar about thirty characters wide and the body in a narrow card while looking at the code.
- The title is a label, two to five words, no verb and no "We": "Two terraform roots", "Postgres node pool", "Bootstrap hand-off to ArgoCD". It names the thing the stop is about; the body says what we did with it.
- The body is two or three bullets, each one short sentence. Say what we chose and why; add what would go wrong otherwise only when it is not obvious.
- One idea per bullet, at most one line of about eighty characters. Vary how
a bullet opens; "We" is fine when it is the natural subject, and a bullet
can also start with the thing itself: "
infraruns first because ...".
Example:
Missing owner list
- `MissingDecision` is raised when `OWNER_EMAILS` is empty.
- A default would silently migrate the rows an owner still has to claim.
- The run stops and names what is missing, at build time, never at login.
Write for the card
Write for a narrow card beside the code:
- Full sentences with their articles and pronouns, in the first person plural
when we are the subject: "We changed X because Y." A sentence may also lead
with the thing itself: "
infraruns first because Y." Do not open every sentence the same way. Cutting words does not make text clearer. - Put every identifier in backticks:
compute_overrides,SHEET_PERMISSIONS,MissingDecision. The card renders markdown; bare identifiers read as prose. - Plain verbs for code: raise, return, check, read, write, fail, skip. No metaphor: no gate, carry, land, surface, shape, vote, mint, unpick, wall, hold an opinion.
- Comparing things, or listing data with several fields per item: a markdown table, header row, two to four columns, one row per thing, identifiers in backticks inside cells. The card rules the columns.
If the diffler tools are missing, the TUI isn't running: ask the human to
run diffler in the repository first.
版本历史
- 78ce09e 当前 2026-11-21 03:49


