@igorlau/dotagents 1.0.13 → 1.0.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +129 -35
- package/THIRD_PARTY_NOTICES.md +76 -2
- package/dist/build-info.json +1 -1
- package/dist/catalog.js +3 -3
- package/dist/cli.js +8 -2
- package/dist/commands.js +60 -5
- package/dist/paths.js +1 -1
- package/dist/targets.js +3 -0
- package/package.json +2 -2
- package/plugin/.claude-plugin/plugin.json +10 -0
- package/plugin/agents/dot-implementer.md +38 -0
- package/plugin/agents/dot-reviewer.md +31 -0
- package/plugin/agents/dot-tester.md +33 -0
- package/plugin/hooks/check.mjs +92 -0
- package/plugin/hooks/hooks.json +24 -0
- package/plugin/rules/code-style.md +6 -0
- package/plugin/rules/comments.md +17 -0
- package/plugin/rules/comments.upstream.json +8 -0
- package/{content → plugin}/rules/ponytail.md +1 -1
- package/{content → plugin}/rules/ponytail.upstream.json +1 -1
- package/plugin/rules/writing.md +35 -0
- package/plugin/rules/writing.upstream.json +8 -0
- package/{content → plugin}/scaffold/AGENTS.md.tmpl +1 -0
- package/plugin/skills/dot-code-review/SKILL.md +71 -0
- package/plugin/skills/dot-code-review/UPSTREAM.json +8 -0
- package/plugin/skills/dot-code-review/references/maintainability.md +67 -0
- package/plugin/skills/dot-comments/SKILL.md +41 -0
- package/plugin/skills/dot-comments/UPSTREAM.json +8 -0
- package/{content → plugin}/skills/dot-commit/SKILL.md +7 -5
- package/plugin/skills/dot-correct/SKILL.md +43 -0
- package/plugin/skills/dot-correct/UPSTREAM.json +8 -0
- package/plugin/skills/dot-correct/agents/openai.yaml +5 -0
- package/plugin/skills/dot-debug/SKILL.md +125 -0
- package/plugin/skills/dot-debug/UPSTREAM.json +8 -0
- package/plugin/skills/dot-debug/references/loops.md +32 -0
- package/{content → plugin}/skills/dot-docs-writing/SKILL.md +15 -23
- package/{content → plugin}/skills/dot-docs-writing/references/formatting.md +26 -26
- package/{content → plugin}/skills/dot-docs-writing/references/global-and-accessible.md +9 -10
- package/{content → plugin}/skills/dot-docs-writing/references/word-list.md +4 -5
- package/plugin/skills/dot-flow/SKILL.md +75 -0
- package/plugin/skills/dot-flow/agents/openai.yaml +5 -0
- package/plugin/skills/dot-flow/references/inline.md +42 -0
- package/{content → plugin}/skills/dot-grill-me/SKILL.md +2 -2
- package/{content → plugin}/skills/dot-grill-me/UPSTREAM.json +1 -1
- package/plugin/skills/dot-grilling/SKILL.md +34 -0
- package/{content → plugin}/skills/dot-grilling/UPSTREAM.json +1 -1
- package/plugin/skills/dot-grilling/agents/openai.yaml +3 -0
- package/plugin/skills/dot-handoff/SKILL.md +20 -0
- package/{content → plugin}/skills/dot-handoff/UPSTREAM.json +1 -1
- package/plugin/skills/dot-implement/SKILL.md +65 -0
- package/plugin/skills/dot-implement/UPSTREAM.json +8 -0
- package/{content → plugin}/skills/dot-implement/references/typescript.md +29 -20
- package/{content → plugin}/skills/dot-plan/SKILL.md +15 -8
- package/plugin/skills/dot-plan/UPSTREAM.json +8 -0
- package/plugin/skills/dot-plan/references/entity-schemas.md +66 -0
- package/{content → plugin}/skills/dot-roadmap/SKILL.md +19 -12
- package/plugin/skills/dot-roadmap/UPSTREAM.json +8 -0
- package/plugin/skills/dot-roadmap/references/wide-refactor.md +3 -0
- package/plugin/skills/dot-testing/SKILL.md +48 -0
- package/plugin/skills/dot-testing/UPSTREAM.json +8 -0
- package/plugin/skills/dot-testing/references/http.md +15 -0
- package/plugin/skills/dot-testing/references/modes.md +32 -0
- package/plugin/skills/dot-testing/references/shared-state.md +3 -0
- package/{content → plugin}/skills/dot-testing/references/typescript.md +2 -2
- package/plugin/skills/dot-writing-for-agents/SKILL.md +54 -0
- package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
- package/plugin/skills/dot-writing-for-agents/references/pointers.md +27 -0
- package/plugin/skills/dot-writing-for-agents/references/skill-mechanics.md +22 -0
- package/plugin/skills/dot-writing-for-agents/references/steps.md +8 -0
- package/content/rules/comments.md +0 -13
- package/content/skills/dot-code-review/SKILL.md +0 -58
- package/content/skills/dot-debug/SKILL.md +0 -142
- package/content/skills/dot-debug/UPSTREAM.json +0 -8
- package/content/skills/dot-grilling/SKILL.md +0 -34
- package/content/skills/dot-grilling/agents/openai.yaml +0 -3
- package/content/skills/dot-handoff/SKILL.md +0 -20
- package/content/skills/dot-implement/SKILL.md +0 -52
- package/content/skills/dot-testing/SKILL.md +0 -44
- package/content/skills/dot-writing-for-agents/SKILL-MECHANICS.md +0 -22
- package/content/skills/dot-writing-for-agents/SKILL.md +0 -85
- package/content/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
- /package/{content → plugin}/rules/core.md +0 -0
- /package/{content → plugin}/scaffold/.claude/settings.json.tmpl +0 -0
- /package/{content → plugin}/scaffold/.editorconfig.tmpl +0 -0
- /package/{content → plugin}/scaffold/.gitattributes.tmpl +0 -0
- /package/{content → plugin}/scaffold/CLAUDE.md.tmpl +0 -0
- /package/{content → plugin}/skills/dot-debug/agents/openai.yaml +0 -0
- /package/{content → plugin}/skills/dot-debug/scripts/hitl-loop.template.sh +0 -0
- /package/{content → plugin}/skills/dot-grill-me/agents/openai.yaml +0 -0
- /package/{content → plugin}/skills/dot-handoff/agents/openai.yaml +0 -0
- /package/{content → plugin}/skills/dot-writing-for-agents/agents/openai.yaml +0 -0
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dot-debug
|
|
3
|
+
description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose" or "debug this", or reports that something is broken, throws, fails, or is slow.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Diagnose bugs
|
|
7
|
+
|
|
8
|
+
Use this method for hard bugs. Skip a phase only when you can state the reason.
|
|
9
|
+
|
|
10
|
+
To learn the modules in the area, read `GLOSSARY.md` if it exists, and read the ADRs for the area that you change.
|
|
11
|
+
|
|
12
|
+
## Repository conventions first
|
|
13
|
+
|
|
14
|
+
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Build the feedback loop with the test framework, scripts, and tools of the repository.
|
|
15
|
+
|
|
16
|
+
## Redact
|
|
17
|
+
|
|
18
|
+
This skill shows commands, outputs, and captured artifacts. Redact every secret first: write `<REDACTED>` in its place. Build loops against environment variables, so the credential stays in the environment and out of what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.
|
|
19
|
+
|
|
20
|
+
If the redacted output is not enough to diagnose the bug, say so and ask the user.
|
|
21
|
+
|
|
22
|
+
## Phase 1: Build a feedback loop
|
|
23
|
+
|
|
24
|
+
This phase is the skill. The other phases are mechanical. With a **tight** pass or fail signal for the bug, one that goes **red** on _this_ bug, you will find the cause. Bisection, hypothesis tests, and instrumentation all use that signal. Without one, the code alone will not show you the bug.
|
|
25
|
+
|
|
26
|
+
Spend most of your effort here. Be aggressive and creative, and do not give up.
|
|
27
|
+
|
|
28
|
+
Start with a test that fails at the seam that reaches the bug. When no test can reach the bug, when the bug is not deterministic, or when you cannot build a loop, read [`references/loops.md`](references/loops.md).
|
|
29
|
+
|
|
30
|
+
### Tighten the loop
|
|
31
|
+
|
|
32
|
+
Treat the loop as a product. When you have _a_ loop, make it **tight**:
|
|
33
|
+
|
|
34
|
+
- Make it faster: cache the setup, skip unrelated startup work, and narrow the test scope.
|
|
35
|
+
- Make the signal sharper: assert on the specific symptom, not on "did not crash".
|
|
36
|
+
- Make it more deterministic: pin the time, seed the random number generator, isolate the filesystem, and freeze the network.
|
|
37
|
+
|
|
38
|
+
A flaky loop of 30 seconds is little better than no loop. A deterministic loop of 2 seconds is tight, and it makes the bug easy to find.
|
|
39
|
+
|
|
40
|
+
### Completion criterion: a tight loop that goes red
|
|
41
|
+
|
|
42
|
+
Phase 1 is done when the loop is **tight** and can go **red**. Name **one command**, such as a script path, a test command, or a curl call. You must have run it at least one time: show the command and its redacted output. The command must be:
|
|
43
|
+
|
|
44
|
+
- [ ] Red-capable: it drives the real bug code path and asserts the user's exact symptom, so it goes red on this bug and green after the fix. A command that only runs without an error is not enough: it must catch this specific bug.
|
|
45
|
+
- [ ] Deterministic: it gives the same verdict on every run. For a flaky bug, it has a pinned, high reproduction rate.
|
|
46
|
+
- [ ] Fast: it takes seconds, not minutes.
|
|
47
|
+
- [ ] Agent-runnable: you can run it without a person. A person can take part only through `scripts/hitl-loop.template.sh`.
|
|
48
|
+
|
|
49
|
+
Do not read code to build a theory before this command exists. A jump to a hypothesis is the exact failure that this skill prevents. Without a red-capable command, do not start Phase 2.
|
|
50
|
+
|
|
51
|
+
## Phase 2: Reproduce and minimize
|
|
52
|
+
|
|
53
|
+
Run the loop. Watch it go red when the bug appears.
|
|
54
|
+
|
|
55
|
+
Confirm:
|
|
56
|
+
|
|
57
|
+
- [ ] The loop produces the failure that the user described, not a different failure nearby. The wrong bug leads to the wrong fix.
|
|
58
|
+
- [ ] The failure occurs on every run, or for a flaky bug, at a rate high enough to debug against.
|
|
59
|
+
- [ ] You captured the exact symptom (the error message, the wrong output, the slow time), so later phases can verify that the fix addresses it.
|
|
60
|
+
|
|
61
|
+
### Minimize
|
|
62
|
+
|
|
63
|
+
When the loop is red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, configuration, data, and steps **one at a time**, and run the loop again after each cut. Keep only what the failure needs.
|
|
64
|
+
|
|
65
|
+
A minimal repro shrinks the set of hypotheses in Phase 3, because fewer parts remain to suspect. It also becomes the clean regression test in Phase 5.
|
|
66
|
+
|
|
67
|
+
Done when **every element that remains is necessary**: when you remove any one of them, the loop goes green.
|
|
68
|
+
|
|
69
|
+
Do not continue until you have reproduced **and** minimized the bug.
|
|
70
|
+
|
|
71
|
+
## Phase 3: Hypothesize
|
|
72
|
+
|
|
73
|
+
Write **3 to 5 ranked hypotheses** before you test any of them. A single hypothesis anchors on the first plausible idea.
|
|
74
|
+
|
|
75
|
+
Each hypothesis must be **falsifiable**: state the prediction that it makes.
|
|
76
|
+
|
|
77
|
+
> Format: "If <X> is the cause, then a change to <Y> makes the bug disappear, and a change to <Z> makes it worse."
|
|
78
|
+
|
|
79
|
+
If you cannot state the prediction, the hypothesis is a guess: drop it or make it sharper.
|
|
80
|
+
|
|
81
|
+
**Show the ranked list to the user before you test it.** The user often has domain knowledge that changes the rank ("we deployed a change to #3"), or knows hypotheses that are already ruled out. If the user does not answer, continue with your rank.
|
|
82
|
+
|
|
83
|
+
## Phase 4: Instrument
|
|
84
|
+
|
|
85
|
+
Map each probe to a specific prediction from Phase 3. **Change one variable at a time.**
|
|
86
|
+
|
|
87
|
+
Use these tools, in this order of preference:
|
|
88
|
+
|
|
89
|
+
1. A debugger or REPL, if the environment supports it. One breakpoint is better than ten logs.
|
|
90
|
+
2. Targeted logs at the boundaries that tell the hypotheses apart.
|
|
91
|
+
3. Never log everything and grep the output.
|
|
92
|
+
|
|
93
|
+
**Tag every debug log** with a unique prefix, such as `[DEBUG-a4f2]`. At the end, one grep finds them all for cleanup.
|
|
94
|
+
|
|
95
|
+
For a performance regression, logs are usually the wrong tool. First, measure a baseline with a harness that measures time, `performance.now()`, a profiler, or a query plan. Then bisect. Measure first, and fix second.
|
|
96
|
+
|
|
97
|
+
## Phase 5: Fix and regression test
|
|
98
|
+
|
|
99
|
+
Fix the root cause, not the symptom. Ask "why" until the answer is the first wrong decision in the code, not a result of an earlier one. Fix every place that has the same pattern. Add a guard only for a state that is legitimate: a guard for a state that must never exist hides the bug.
|
|
100
|
+
|
|
101
|
+
When two fixes fail the same check, write down the premise that both fixes assumed. Test the premise before you write a third fix.
|
|
102
|
+
|
|
103
|
+
Write the regression test **before the fix**, but only if a **correct seam** exists for it.
|
|
104
|
+
|
|
105
|
+
A correct seam is one where the test runs the **real bug pattern** as it occurs at the call site. Sometimes the only seam is too shallow: a test with one caller when the bug needs several callers, or a unit test that cannot repeat the chain that triggered the bug. A regression test there gives false confidence.
|
|
106
|
+
|
|
107
|
+
**If no correct seam exists, that is the finding.** Note it. The architecture of the codebase prevents a test that locks the bug down. Flag it for the next phase.
|
|
108
|
+
|
|
109
|
+
If a correct seam exists:
|
|
110
|
+
|
|
111
|
+
1. Turn the minimized repro into a test that fails at that seam.
|
|
112
|
+
2. Watch it fail. If you forced the red with a change to code or a fixture, `diff` against a clean copy to prove that the change landed before you trust it.
|
|
113
|
+
3. Apply the fix.
|
|
114
|
+
4. Watch the test pass.
|
|
115
|
+
5. Run the Phase 1 feedback loop again against the original scenario, before minimization.
|
|
116
|
+
|
|
117
|
+
## Phase 6: Clean up
|
|
118
|
+
|
|
119
|
+
Do these before you declare the work done:
|
|
120
|
+
|
|
121
|
+
- [ ] The original repro no longer reproduces: run the Phase 1 loop again.
|
|
122
|
+
- [ ] The regression test passes, or you documented that no correct seam exists.
|
|
123
|
+
- [ ] All `[DEBUG-...]` instrumentation is removed: grep the prefix.
|
|
124
|
+
- [ ] Throwaway prototypes are deleted, or moved to a clearly marked debug location.
|
|
125
|
+
- [ ] The commit or pull request message states the hypothesis that was correct, so the next person who debugs the code learns from it.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
{
|
|
2
|
+
"repository": "https://github.com/mattpocock/skills",
|
|
3
|
+
"path": "skills/engineering/diagnosing-bugs",
|
|
4
|
+
"commit": "49dd158d1076134a641b33efb035946536778336",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"modified": true,
|
|
7
|
+
"notes": "Renamed from diagnosing-bugs to debug (frontmatter name and display_name). Added a 'Repository conventions first' section. Renamed with the dot- prefix. Added the root cause and premise rules to Phase 5, condensed from pstack/skills/principle-fix-root-causes and pstack/skills/principle-attack-the-premise in https://github.com/cursor/plugins at commit a5539b15a3d56e04992565aafee2b37051329ce3 (MIT). Rewrote the text under plugin/rules/writing.md. Moved the ways to build a loop, the bugs that are not deterministic, and the case with no loop to references/loops.md."
|
|
8
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Feedback loops
|
|
2
|
+
|
|
3
|
+
## Ways to build a loop
|
|
4
|
+
|
|
5
|
+
Try these in about this order:
|
|
6
|
+
|
|
7
|
+
1. A test that fails at the seam that reaches the bug: unit, integration, or end-to-end.
|
|
8
|
+
2. A curl or HTTP script against a dev server that runs locally.
|
|
9
|
+
3. A CLI call with a fixture input, with a diff of stdout against a known good snapshot.
|
|
10
|
+
4. A headless browser script (Playwright or Puppeteer) that drives the UI and asserts on the DOM, the console, or the network.
|
|
11
|
+
5. A replay of a captured trace. Save a real network request, payload, or event log to disk, and replay it through the code path alone.
|
|
12
|
+
6. A throwaway harness. Start a minimal subset of the system, such as one service with stubbed dependencies, that runs the bug code path with one function call.
|
|
13
|
+
7. A property or fuzz loop. If the bug is "sometimes wrong output", run 1,000 random inputs and look for the failure.
|
|
14
|
+
8. A bisection harness. If the bug appeared between two known states (a commit, a dataset, a version), automate "start at state X, check, repeat", so you can use `git bisect run`.
|
|
15
|
+
9. A differential loop. Run the same input through the old and the new version, or through two configurations, and diff the outputs.
|
|
16
|
+
10. A human-in-the-loop bash script, as the last resort. If a person must click, drive the person with [`scripts/hitl-loop.template.sh`](../scripts/hitl-loop.template.sh), so the loop keeps its structure. The captured output comes back to you.
|
|
17
|
+
|
|
18
|
+
With the right feedback loop, the bug is 90% fixed.
|
|
19
|
+
|
|
20
|
+
## Bugs that are not deterministic
|
|
21
|
+
|
|
22
|
+
The goal is not a clean repro. The goal is a **higher reproduction rate**. Run the trigger 100 times, run copies in parallel, add stress, narrow the time windows, and add sleeps. A bug that fails 50% of the time is easy to debug, and a bug that fails 1% of the time is not. Raise the rate until you can debug the bug.
|
|
23
|
+
|
|
24
|
+
## When you cannot build a loop
|
|
25
|
+
|
|
26
|
+
Stop and say so. List what you tried. Ask the user for one of these:
|
|
27
|
+
|
|
28
|
+
- Access to the environment that reproduces the bug.
|
|
29
|
+
- A redacted captured artifact: a HAR file, a log dump, a core dump, or a video of the screen with timestamps.
|
|
30
|
+
- Permission to add temporary instrumentation in production.
|
|
31
|
+
|
|
32
|
+
Do **not** start to form hypotheses without a loop.
|
|
@@ -1,47 +1,40 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dot-docs-writing
|
|
3
|
-
description: Write and edit developer documentation in the Google developer documentation style. Use when
|
|
3
|
+
description: Write and edit developer documentation in the Google developer documentation style. Use when you create or revise a README, guide, tutorial, reference page, changelog, or code comments meant for readers.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Docs writing
|
|
7
7
|
|
|
8
|
-
Write documentation that a developer in a hurry,
|
|
8
|
+
Write documentation that a developer in a hurry, who reads in their second language, can follow on the first pass. This skill covers the frame, structure, and format of a document, based on the Google developer documentation style guide. The always-on writing rule governs the prose, and it wins any conflict with this skill.
|
|
9
9
|
|
|
10
10
|
## Repository conventions first
|
|
11
11
|
|
|
12
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the
|
|
12
|
+
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. This includes the project's documentation style guide, prose linter configuration such as Vale, and the structure and terms of its current docs.
|
|
13
13
|
|
|
14
14
|
## 1. Frame the document
|
|
15
15
|
|
|
16
|
-
Before
|
|
16
|
+
Before you draft, answer these questions:
|
|
17
17
|
|
|
18
18
|
- **Reader**: who is "you" in this document (an app developer, an operator, a contributor), and what do they already know?
|
|
19
|
-
- **Goal**: what can the reader do after
|
|
19
|
+
- **Goal**: what can the reader do after they read the document?
|
|
20
20
|
- **Type**: a task (how to do something), a concept (how something works), or reference (facts to look up). Use a task title with a bare verb, such as "Deploy the service", and a concept title with a noun phrase, such as "Deployment model".
|
|
21
21
|
|
|
22
|
-
## 2. Draft
|
|
22
|
+
## 2. Draft
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
- Write like a knowledgeable colleague: conversational and direct, without slang, jokes, or hype.
|
|
27
|
-
- Address the reader as "you". Use the imperative for instructions. Use "we" only for a named organization.
|
|
28
|
-
- Use active voice and name the actor: "The server sends a response", not "A response is sent".
|
|
29
|
-
- Use present tense. Use "will" only for events that happen later.
|
|
30
|
-
- Use common contractions, such as "don't" and "isn't".
|
|
31
|
-
- Write "click **Save**", not "please click" or "simply click". Words such as "simply", "easy", "just", and "quickly" judge difficulty for the reader, so leave them out.
|
|
24
|
+
Write the prose by the writing rule. Then apply these rules for documents:
|
|
32
25
|
|
|
33
26
|
**Sentences**
|
|
34
27
|
|
|
35
|
-
-
|
|
28
|
+
- Address the reader as "you". Use "we" only for a named organization.
|
|
36
29
|
- Put the condition before the instruction: "If the build fails, run `make clean`."
|
|
37
30
|
- Put the goal before the action: "To create a folder, click **New**."
|
|
38
|
-
-
|
|
39
|
-
- Replace
|
|
40
|
-
-
|
|
31
|
+
- Spell out an abbreviation at its first use.
|
|
32
|
+
- Replace an unclear pronoun, such as "it" or "this", with the noun.
|
|
33
|
+
- Write "click **Save**", not "please click" or "simply click". Words such as "simply", "easy", and "quickly" judge difficulty for the reader.
|
|
41
34
|
|
|
42
35
|
**Structure**
|
|
43
36
|
|
|
44
|
-
-
|
|
37
|
+
- Keep heading levels in order, and use one level-1 heading per page.
|
|
45
38
|
- Introduce every list, table, code sample, and procedure with a complete sentence that ends in a colon.
|
|
46
39
|
- Use numbered lists for sequences and bulleted lists for everything else. Keep list items parallel.
|
|
47
40
|
- Write each procedure step as one imperative action. State where the action happens before the action.
|
|
@@ -50,7 +43,7 @@ Before drafting, answer these questions:
|
|
|
50
43
|
**Formatting**
|
|
51
44
|
|
|
52
45
|
- Put code-related text in code font: commands, filenames, paths, variables, values, and field input.
|
|
53
|
-
- Put UI element names in bold,
|
|
46
|
+
- Put UI element names in bold, with the label's capitalization: click **Create project**.
|
|
54
47
|
- Write placeholders in uppercase with underscores, such as `PROJECT_ID`, and explain each one after the sample.
|
|
55
48
|
- Use descriptive link text, such as the page title. Never use "click here" or a bare URL.
|
|
56
49
|
- Write dates as "January 19, 2026", or as ISO 8601 (`2026-01-19`) when space is tight.
|
|
@@ -61,8 +54,7 @@ Before drafting, answer these questions:
|
|
|
61
54
|
Read the draft once per checklist item, and fix every instance:
|
|
62
55
|
|
|
63
56
|
- [ ] Each heading matches its section type (task, concept, or reference).
|
|
64
|
-
- [ ]
|
|
65
|
-
- [ ] No sentence exceeds 26 words.
|
|
57
|
+
- [ ] Every sentence follows the writing rule: its word limit, the active voice, and no contractions.
|
|
66
58
|
- [ ] Every list, table, and code block has an introductory sentence.
|
|
67
59
|
- [ ] Every placeholder is explained.
|
|
68
60
|
- [ ] Every command and code sample runs as written, apart from its placeholders.
|
|
@@ -71,7 +63,7 @@ Read the draft once per checklist item, and fix every instance:
|
|
|
71
63
|
|
|
72
64
|
## References
|
|
73
65
|
|
|
74
|
-
Load the reference that matches
|
|
66
|
+
Load the reference that matches the document:
|
|
75
67
|
|
|
76
68
|
- [`references/formatting.md`](references/formatting.md): headings, lists, tables, procedures, code samples, commands, placeholders, notices, links, UI elements, and dates in detail.
|
|
77
69
|
- [`references/word-list.md`](references/word-list.md): words and phrases to avoid, with replacements. Read it during the revision pass.
|
|
@@ -1,26 +1,26 @@
|
|
|
1
1
|
# Formatting reference
|
|
2
2
|
|
|
3
|
-
Detailed
|
|
3
|
+
Detailed format rules for the [`dot-docs-writing`](../SKILL.md) skill.
|
|
4
4
|
|
|
5
5
|
## Headings and titles
|
|
6
6
|
|
|
7
7
|
- Use sentence case: "Transfer data sets", not "Transfer Data Sets".
|
|
8
8
|
- Start task headings with a bare verb: "Create an instance", not "Creating an instance".
|
|
9
|
-
- Write concept headings as noun phrases that
|
|
9
|
+
- Write concept headings as noun phrases that do not start with an -ing verb: "Migration to the cloud".
|
|
10
10
|
- Gerunds are acceptable only when no better option exists, such as "Billing".
|
|
11
11
|
- Prefix optional sections with "Optional:", as in "Optional: Customize your alias".
|
|
12
|
-
- Use exactly one level-1 heading per page, and make it unique in the doc set.
|
|
13
|
-
-
|
|
12
|
+
- Use exactly one level-1 heading per page, and make it unique in the doc set. Do not repeat the page title as a section heading.
|
|
13
|
+
- Do not skip levels: a level-3 heading belongs under a level-2 heading.
|
|
14
14
|
- Follow every heading with content.
|
|
15
|
-
-
|
|
15
|
+
- Do not number headings to show sequence, and do not put links in headings.
|
|
16
16
|
- Avoid code in headings. If you must, add a descriptive noun, such as "The `init` command".
|
|
17
|
-
- Keep heading punctuation minimal. Heavy punctuation means the heading needs
|
|
17
|
+
- Keep heading punctuation minimal. Heavy punctuation means the heading needs a rewrite.
|
|
18
18
|
- Introduce a group of subsections with "the following sections", not "this section" or "these sections".
|
|
19
19
|
|
|
20
20
|
## Lists
|
|
21
21
|
|
|
22
|
-
- Use a numbered list when order matters, a bulleted list when it
|
|
23
|
-
-
|
|
22
|
+
- Use a numbered list when order matters, a bulleted list when it does not, and a description list for term-definition pairs.
|
|
23
|
+
- Do not make a list of one item.
|
|
24
24
|
- Introduce a list with a complete sentence. End the sentence with a colon if the list follows immediately, or with a period if other material comes between them.
|
|
25
25
|
- Recommended: "Use the **Submit** button for any of the following purposes:"
|
|
26
26
|
- Not recommended: "Use the **Submit** button to:"
|
|
@@ -28,15 +28,15 @@ Detailed formatting rules for the [`dot-docs-writing`](../SKILL.md) skill.
|
|
|
28
28
|
- Start each item with a capital letter.
|
|
29
29
|
- End items with a period unless the item is a single word, has no verb, is entirely code, or is entirely link text. When items are mixed, make them parallel or punctuate all of them.
|
|
30
30
|
- In run-in lists, separate the bold term from its description with a colon or a period, and use the same punctuation for every item.
|
|
31
|
-
- In prose lists,
|
|
31
|
+
- In prose lists, do not end with "etc." or "and so on". Introduce the list so that it is clearly not exhaustive, for example with "including".
|
|
32
32
|
- Nest sequential sub-items with lowercase letters, and their sub-items with lowercase Roman numerals.
|
|
33
33
|
|
|
34
34
|
## Tables
|
|
35
35
|
|
|
36
36
|
- Use a table when each item has three or more related pieces of data. A one-column table should be a list.
|
|
37
37
|
- Introduce each table with a complete sentence that states its purpose.
|
|
38
|
-
- Use sentence case for column headings, without
|
|
39
|
-
-
|
|
38
|
+
- Use sentence case for column headings, without punctuation at the end.
|
|
39
|
+
- Do not merge cells, and do not put a table in the middle of a numbered procedure.
|
|
40
40
|
- Sort rows logically, or alphabetically when no logical order exists.
|
|
41
41
|
- Refer to a table by its position, such as "the following table", not "the table below".
|
|
42
42
|
|
|
@@ -52,7 +52,7 @@ Detailed formatting rules for the [`dot-docs-writing`](../SKILL.md) skill.
|
|
|
52
52
|
- State the action, then its reason: "Store the token safely. You need it to sign in later."
|
|
53
53
|
- Order a complex step as follows: action, command, placeholder explanations, further explanation, output, result.
|
|
54
54
|
- List prerequisites (hardware, software, permissions, information) before the first step.
|
|
55
|
-
- When two procedures share steps, link to the earlier one
|
|
55
|
+
- When two procedures share steps, link to the earlier one, and do not repeat it.
|
|
56
56
|
- Document one method, the shortest one that works for every reader. Separate alternatives with headings or tabs only when necessary.
|
|
57
57
|
|
|
58
58
|
## Code in text
|
|
@@ -68,30 +68,30 @@ Use code font for the following items:
|
|
|
68
68
|
- Text that the reader types and command output.
|
|
69
69
|
- Placeholders.
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
Do not use code font for product names, domain names in prose, or URLs that the reader visits in a browser.
|
|
72
72
|
|
|
73
|
-
Use code names grammatically as proper nouns.
|
|
73
|
+
Use code names grammatically as proper nouns. Do not pluralize them, make them possessive, or turn them into verbs. Add a plain noun instead:
|
|
74
74
|
|
|
75
75
|
- Recommended: "The `ADDRESS` constant's value", "send a `POST` request".
|
|
76
76
|
- Not recommended: "`ADDRESS`'s value", "`POST` the data".
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
Do not wrap code in quotation marks unless the quotation marks are part of the code.
|
|
79
79
|
|
|
80
80
|
## Code samples
|
|
81
81
|
|
|
82
82
|
- Introduce each sample with a sentence that ends in a colon.
|
|
83
83
|
- Use fenced code blocks with a language tag.
|
|
84
84
|
- Wrap lines at 80 characters.
|
|
85
|
-
- Mark omitted code with a comment in the sample's language.
|
|
85
|
+
- Mark omitted code with a comment in the sample's language. Do not use an ellipsis.
|
|
86
86
|
- Follow the language's own style guide, or the project's.
|
|
87
87
|
|
|
88
88
|
## Commands
|
|
89
89
|
|
|
90
90
|
- Make copyable commands runnable as written, apart from placeholders.
|
|
91
|
-
- Link each command to its reference documentation where it
|
|
91
|
+
- Link each command to its reference documentation where it is introduced.
|
|
92
92
|
- Show as few optional flags as possible. Point to the reference for the rest.
|
|
93
93
|
- Break long commands before a flag, end each continued line with ` \` (or ` ^` on Windows), and indent continuation lines four spaces.
|
|
94
|
-
- In multi-line examples, start each input line with `$`. If a document mixes one-line and multi-line commands, use the prompt for all of them.
|
|
94
|
+
- In multi-line examples, start each input line with `$`. If a document mixes one-line and multi-line commands, use the prompt for all of them. Do not show the current directory.
|
|
95
95
|
- Put input and output in separate code blocks.
|
|
96
96
|
- Show output only when the reader needs to verify or copy a value. Introduce it with "The output is similar to the following:". Mark omitted lines with `...` on a line of its own.
|
|
97
97
|
- In syntax descriptions, wrap optional arguments in `[]`, mutually exclusive choices in `{a|b}`, and mark repeatable arguments with `...`. Keep these symbols out of copyable commands.
|
|
@@ -111,7 +111,7 @@ Don't wrap code in quotation marks unless the quotation marks are part of the co
|
|
|
111
111
|
- **Note:** relevant but optional information that the reader can skip.
|
|
112
112
|
- **Caution:** proceed carefully.
|
|
113
113
|
- **Warning:** an action might cause irreversible harm, such as data loss, cost, or a security exposure.
|
|
114
|
-
-
|
|
114
|
+
- Do not use a notice for prerequisites, required steps, results, or cross-references. Put that information in the main text.
|
|
115
115
|
- Start each notice with its bold label and a colon: "**Note:**".
|
|
116
116
|
|
|
117
117
|
## Links
|
|
@@ -119,17 +119,17 @@ Don't wrap code in quotation marks unless the quotation marks are part of the co
|
|
|
119
119
|
- Use the destination's page title, or a short descriptive phrase with the key words first, as link text.
|
|
120
120
|
- Never use "click here", "this page", "this document", or a bare URL as link text.
|
|
121
121
|
- Introduce cross-references with "For more information, see LINK." or "For more information about TOPIC, see LINK."
|
|
122
|
-
- Link only what
|
|
123
|
-
- Say when a link downloads a file or leaves the doc set.
|
|
124
|
-
- Keep punctuation outside the link text, and
|
|
122
|
+
- Link only what is relevant, and do not repeat a link to the same destination on one page.
|
|
123
|
+
- Say when a link downloads a file or leaves the doc set. Do not force new tabs.
|
|
124
|
+
- Keep punctuation outside the link text, and do not put link text in quotation marks.
|
|
125
125
|
|
|
126
126
|
## UI elements
|
|
127
127
|
|
|
128
|
-
- Put UI element names in bold,
|
|
128
|
+
- Put UI element names in bold, with their capitalization on screen. Use sentence case if the label is all caps.
|
|
129
129
|
- Name the element and its type: "the **Name** field", "the **File** menu", "the **Advanced** tab".
|
|
130
|
-
- Use "click" for buttons and links, "select" and "clear" for checkboxes and options, "enter" for text, and "press" for keys.
|
|
130
|
+
- Use "click" for buttons and links, "select" and "clear" for checkboxes and options, "enter" for text, and "press" for keys. Do not write "click on", "hit", "check", or "uncheck".
|
|
131
131
|
- Use "in" with dialogs, fields, lists, menus, panes, and windows, and "on" with pages, tabs, and toolbars.
|
|
132
|
-
-
|
|
132
|
+
- Do not use a UI label as a verb: "To save the file, click **Save**", not "**Save** the file".
|
|
133
133
|
- Write key combinations with spelled-out modifier names: Control+S. For several operating systems, give Windows and Linux first and macOS in parentheses.
|
|
134
134
|
|
|
135
135
|
## Dates and times
|
|
@@ -137,7 +137,7 @@ Don't wrap code in quotation marks unless the quotation marks are part of the co
|
|
|
137
137
|
- Write dates with the full month and a four-digit year: "January 19, 2026". Abbreviate only in tables or headings: "Jan 19, 2026".
|
|
138
138
|
- When a numeric date is unavoidable, use ISO 8601: `2026-01-19`.
|
|
139
139
|
- Use the 12-hour clock with AM or PM: "3:45 PM", "3 PM". Use 24-hour time only when the product uses it.
|
|
140
|
-
- Avoid time zones unless they
|
|
140
|
+
- Avoid time zones unless they are necessary. Spell out the region and add the UTC offset: "Pacific Standard Time (UTC-8)".
|
|
141
141
|
- Avoid seasons, because they differ between hemispheres. Use months or quarters.
|
|
142
142
|
|
|
143
143
|
## Numbers
|
|
@@ -6,38 +6,37 @@ Rules for the [`dot-docs-writing`](../SKILL.md) skill that help readers who use
|
|
|
6
6
|
|
|
7
7
|
- Use simple words: "start", not "commence"; "so", not "consequently"; "some" or "many", not "a number of".
|
|
8
8
|
- Prefer one-word verbs to phrasal verbs, except standard terms such as "set up" and "sign in".
|
|
9
|
-
- Use each word in its primary sense, and
|
|
9
|
+
- Use each word in its primary sense, and do not use the same word as a noun and a verb close together.
|
|
10
10
|
- Use subject-verb-object order, and keep the subject and verb near the start of the sentence.
|
|
11
11
|
- Keep helper words that make structure explicit: "that", "then", "of". Write "Update the rules that you defined", not "Update the rules you defined".
|
|
12
12
|
- Write "if X, then Y" in technical conditions.
|
|
13
13
|
- Place "only" directly before the word it modifies.
|
|
14
|
-
-
|
|
15
|
-
- Replace "using" with "by using" or "that uses" when the meaning is unclear.
|
|
14
|
+
- Replace "using" with "with", "through", or "that uses".
|
|
16
15
|
- Avoid idioms, metaphors, humor, slang, pop culture, sports references, and holidays.
|
|
17
16
|
- Use a diverse set of names in examples, and use example domains such as `example.com`.
|
|
18
17
|
- Address the reader as "you". Use "users" only for the people who use the software that the reader builds.
|
|
19
|
-
- State what the reader can do instead of what they
|
|
18
|
+
- State what the reader can do instead of what they cannot.
|
|
20
19
|
|
|
21
20
|
## Accessibility
|
|
22
21
|
|
|
23
22
|
- Break text into short paragraphs, headings, and lists. Put the key information in the first sentence of each paragraph.
|
|
24
|
-
-
|
|
23
|
+
- Avoid double negatives and exceptions to exceptions.
|
|
25
24
|
- Define acronyms at first use, and again if they appear rarely.
|
|
26
25
|
- Write link text that makes sense out of context, because screen reader users often navigate by links alone.
|
|
27
26
|
- Give every image alt text that conveys its purpose. Use empty alt text for decorative images.
|
|
28
27
|
- Never put information only in an image, and never use images of text, code, or terminal output.
|
|
29
|
-
-
|
|
28
|
+
- Do not rely on color, size, position, or shape alone. Pair each with a text label.
|
|
30
29
|
- Refer to UI elements by their labels, not by appearance ("the bell icon") or position ("on the right").
|
|
31
30
|
- Use "and", not "&", except in UI labels and code.
|
|
32
|
-
-
|
|
33
|
-
-
|
|
31
|
+
- Do not rely on punctuation alone to carry meaning, because some screen readers skip it.
|
|
32
|
+
- Do not insert hard line breaks inside sentences.
|
|
34
33
|
- Introduce every table, and use header cells for the first row or column only.
|
|
35
|
-
- Provide captions or transcripts for audio and video, and avoid
|
|
34
|
+
- Provide captions or transcripts for audio and video, and avoid content that flashes.
|
|
36
35
|
|
|
37
36
|
## Inclusive language
|
|
38
37
|
|
|
39
38
|
- Use gender-neutral language. Use "they" for a person of unknown gender.
|
|
40
|
-
- Use people-first or identity-first language as each community prefers.
|
|
39
|
+
- Use people-first or identity-first language as each community prefers. Do not describe people without disabilities as "normal" or "healthy".
|
|
41
40
|
- Replace terms with violent, ableist, or oppressive connotations. See the inclusive language table in [`word-list.md`](word-list.md).
|
|
42
41
|
- When code requires a non-inclusive term, use it only in code font, and use the inclusive term in prose.
|
|
43
42
|
|
|
@@ -16,9 +16,8 @@ These words add nothing, or judge difficulty for the reader:
|
|
|
16
16
|
| latest, new, soon, eventually, in the future | A version number or date. |
|
|
17
17
|
| performant | A precise measure, such as "responds in under 100 ms". |
|
|
18
18
|
| functionality | features, capabilities |
|
|
19
|
-
| leverage, utilize | use |
|
|
20
19
|
| desire, wish | want, need |
|
|
21
|
-
| via | through,
|
|
20
|
+
| via | through, with |
|
|
22
21
|
| learnings | lessons, things you learned |
|
|
23
22
|
| allows you to | lets you |
|
|
24
23
|
|
|
@@ -29,7 +28,7 @@ These words have more than one meaning:
|
|
|
29
28
|
| Avoid | Write instead |
|
|
30
29
|
|-------|---------------|
|
|
31
30
|
| should | must (required), can (optional), or a recommendation: "We recommend…" |
|
|
32
|
-
| may | can
|
|
31
|
+
| may, might | can |
|
|
33
32
|
| could, would | can |
|
|
34
33
|
| will | Present tense, unless the event happens later. |
|
|
35
34
|
| once (meaning "after") | after |
|
|
@@ -49,7 +48,7 @@ These words have more than one meaning:
|
|
|
49
48
|
| Avoid | Write instead |
|
|
50
49
|
|-------|---------------|
|
|
51
50
|
| abort, kill, terminate (generic) | stop, exit, cancel, end |
|
|
52
|
-
| hang, hung | stops responding,
|
|
51
|
+
| hang, hung | stops responding, is not responding |
|
|
53
52
|
| hit (a key or button) | press, click |
|
|
54
53
|
| hover over | hold the pointer over, point to |
|
|
55
54
|
| click on | click |
|
|
@@ -85,7 +84,7 @@ These words have more than one meaning:
|
|
|
85
84
|
| whitelist, blacklist | allowlist, denylist or blocklist |
|
|
86
85
|
| master, slave | primary, main, leader, controller; replica, secondary, worker |
|
|
87
86
|
| sanity check | quick check, confidence check |
|
|
88
|
-
| crazy, insane, sane | unexpected,
|
|
87
|
+
| crazy, insane, sane | unexpected, strange, valid, sensible |
|
|
89
88
|
| cripple | slow down, break |
|
|
90
89
|
| blind to, turn a blind eye | unaware of, ignore |
|
|
91
90
|
| dumb down | simplify |
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dot-flow
|
|
3
|
+
description: Take one roadmap task through test stubs, implementation, test fill, and review, with your approval after each step.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Flow
|
|
8
|
+
|
|
9
|
+
Take one task from a `dot-roadmap` roadmap through four steps: test stubs, implementation, test fill, and review. Each step runs in a fresh agent with one skill, and the user approves its result before the next step starts. You coordinate the steps. The agents write the tests, the code, and the review.
|
|
10
|
+
|
|
11
|
+
## Repository conventions first
|
|
12
|
+
|
|
13
|
+
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard.
|
|
14
|
+
|
|
15
|
+
## 1. Pin the task
|
|
16
|
+
|
|
17
|
+
The input is a roadmap task file or a roadmap directory. With a directory, pick the lowest-id unticked task whose blockers are all ticked in its `README.md`. If the task has an unticked blocker, stop and name it.
|
|
18
|
+
|
|
19
|
+
Run `git status --short`. The review step reads every uncommitted change, so when the working tree has other changes, ask the user to commit them first or to include them in the review.
|
|
20
|
+
|
|
21
|
+
Done when you can name the task file and its goal.
|
|
22
|
+
|
|
23
|
+
## 2. Pick the runner
|
|
24
|
+
|
|
25
|
+
Use the agents of the dotagents plugin when the `Agent` tool can start them: `dotagents:dot-tester`, `dotagents:dot-implementer`, and `dotagents:dot-reviewer`. Otherwise, such as in Codex or Copilot, read [`references/inline.md`](references/inline.md), and run each step inline with the same approvals.
|
|
26
|
+
|
|
27
|
+
## 3. Run the steps
|
|
28
|
+
|
|
29
|
+
Run the steps in this order. For each step, start a new agent of the named type, not a fork, so that each step starts with a fresh context:
|
|
30
|
+
|
|
31
|
+
| Step | Agent | Prompt fields |
|
|
32
|
+
| ---- | ----- | ------------- |
|
|
33
|
+
| 1. Stub | `dotagents:dot-tester` | Task, Mode `stub` |
|
|
34
|
+
| 2. Implement | `dotagents:dot-implementer` | Task, Handoff: the reply of step 1 |
|
|
35
|
+
| 3. Fill | `dotagents:dot-tester` | Task, Mode `fill`, Handoff: the reply of step 2 |
|
|
36
|
+
| 4. Review | `dotagents:dot-reviewer` | Task, Handoff: the replies of steps 1 to 3 |
|
|
37
|
+
|
|
38
|
+
Write the prompt as labeled fields, and leave out a field that the step does not take:
|
|
39
|
+
|
|
40
|
+
```markdown
|
|
41
|
+
**Task:** <path of the task file>
|
|
42
|
+
**Mode:** <stub | fill>
|
|
43
|
+
**Handoff:**
|
|
44
|
+
<the replies of the earlier steps, unchanged>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Copy the replies unchanged, because the agents read their fields. Keep the main context small: do not read the changed files or the full test output yourself. The replies carry what the user needs.
|
|
48
|
+
|
|
49
|
+
## 4. Approve each step
|
|
50
|
+
|
|
51
|
+
After each step, show the user this summary, then wait:
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
**Step <n> of 4: <step name>**
|
|
55
|
+
<the Summary line of the reply>
|
|
56
|
+
<the Checks or Tests line of the reply>
|
|
57
|
+
**Blockers:** <the Blockers line of the reply>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
For the review step, show the **Highest severity** line and one line for each finding: its severity, summary, and `file:line`.
|
|
61
|
+
|
|
62
|
+
Start the next step only when the user says "go" or approves in other words. When the user asks for a change, run the same step again in a new agent, and add the request to the prompt.
|
|
63
|
+
|
|
64
|
+
Stop the flow, and keep the files as they are, in these cases:
|
|
65
|
+
|
|
66
|
+
- A reply has blockers. Show them, and ask the user how to continue.
|
|
67
|
+
- The review reports a `high` finding. The presumed blockers of the maintainability pass are `high`. Show each `high` finding with its **Fix** line. When the user fixes the findings and asks for a new review, run step 4 again.
|
|
68
|
+
|
|
69
|
+
Done when the user approved the review step, or the flow stopped.
|
|
70
|
+
|
|
71
|
+
## 5. Finish
|
|
72
|
+
|
|
73
|
+
List the files that the steps changed, from the **Files** lines of the replies. The user decides about the `medium` and `low` findings. Suggest the `dot-commit` skill.
|
|
74
|
+
|
|
75
|
+
Do not commit, and do not tick the roadmap checkbox: `dot-commit` ticks it when the commits finish the task.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Inline mode
|
|
2
|
+
|
|
3
|
+
Inline steps for the [`dot-flow`](../SKILL.md) skill, for an agent that cannot start the dotagents agents, such as Codex or Copilot. The steps, the approvals, and the stop cases of `SKILL.md` stay the same. You run each step yourself, in this conversation, instead of in an agent.
|
|
4
|
+
|
|
5
|
+
## Steps
|
|
6
|
+
|
|
7
|
+
1. Stub: use the `dot-testing` skill in stub mode for the task.
|
|
8
|
+
2. Implement: use the `dot-implement` skill for the task, with the reply of step 1.
|
|
9
|
+
3. Fill: use the `dot-testing` skill in fill mode for the task, with the reply of step 2.
|
|
10
|
+
4. Review: use the `dot-code-review` skill for the task. The target is `git diff HEAD`, plus the untracked files that `git status --short` lists. Report the findings, and keep the code as it is. Delete each test that you write to prove a finding.
|
|
11
|
+
|
|
12
|
+
Do only the work of the current step, even when the next step looks small. The steps share one context, so read only what the current step needs.
|
|
13
|
+
|
|
14
|
+
## Replies
|
|
15
|
+
|
|
16
|
+
End each step with its reply, then show the summary of `SKILL.md` step 4. Keep each summary to 3 sentences or fewer.
|
|
17
|
+
|
|
18
|
+
Steps 1 and 3:
|
|
19
|
+
|
|
20
|
+
```markdown
|
|
21
|
+
**Summary:** <what you did>
|
|
22
|
+
**Tests:** <the test command and its result line>
|
|
23
|
+
**Files:** <the test files that you changed>
|
|
24
|
+
**Blockers:** <what stops the next step, or "none">
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Step 2, with the handoff fields from step 5 of `dot-implement`:
|
|
28
|
+
|
|
29
|
+
```markdown
|
|
30
|
+
**Summary:** <what you did>
|
|
31
|
+
**Checks:** <the type checker, linter, and test commands, with their result lines>
|
|
32
|
+
**Files:** <the production files that you changed>
|
|
33
|
+
**Blockers:** <what stops the next step, or "none">
|
|
34
|
+
|
|
35
|
+
**Expected failures:**
|
|
36
|
+
- `<test file>`: <test name>: <the new behavior that the test must assert>
|
|
37
|
+
|
|
38
|
+
**Behaviors that need tests:**
|
|
39
|
+
- `<module>`: <a behavior that the change adds or changes, and that no test case covers>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Step 4: start with the line `**Highest severity:** <high | medium | low | none>`, then give the report of `dot-code-review`.
|
|
@@ -4,8 +4,8 @@ description: A relentless interview to sharpen a plan or design.
|
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Use the `dot-grilling` skill to interview the user about the plan or design they describe.
|
|
7
|
+
Use the `dot-grilling` skill to interview the user about the plan or design that they describe.
|
|
8
8
|
|
|
9
9
|
## Repository conventions first
|
|
10
10
|
|
|
11
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the
|
|
11
|
+
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Base the recommendations of the interview on those conventions.
|