test-outline
Skill759 starsChanged todayMITView on GitHub
Use before writing, adding or reworking Ginkgo specs in kuik; drafts the It/Entry strings as pending specs, has spec-reviewer check them and shows them with task test-outline before any body is written.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- acceptance-scenariosSkill
- decision-noteSkill
- e2e-specSkill
- pull-requestSkill
- release-acceptanceSkill
- release-notesSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 4 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Read what defines the behaviour: the section of docs/v3/spec.md or docs/v3/status.md, or the walkthrough under docs/v3/.
- Very specific: line 18
Read the package's *_test.go to reuse its Describe structure and helpers.
- Very specific: line 19
Never invent behaviour. When the spec is silent or ambiguous, decide: what the kubelet does first, then the most literal reading of …
- Very specific: line 33
No implementation detail: "sets Ready to False when the destination registry is unreachable", not "calls probe()".
- Distinctive: line 39
Add the stubs the outline needs to compile (a type, a function returning its zero value), nothing more.
- Very specific: line 89
Before showing it, hand the outline and the spec section it covers to the spec-reviewer sub-agent.
- Distinctive: line 114
When the user asks for changes, apply them to the strings, and to the bodies already written, then show the outline again and go on.
- Very specific: line 119
Keep a todo list with Claude Code's task tools for the pull request, one task per step of the plan (each outline group, each test/feat …
- Distinctive: line 148
Never rename a string while filling.
- Very specific: line 149
Never edit a test to make it pass.
- Very specific: line 152
When a review (reviewer, human, CodeRabbit) finds a bug the outline missed in code a commit of this branch adds, its regression spec is a …
- Distinctive: line 161
Run the case alone, then the package:
- Very specific: line 168
Run task manifests first when a type changed: envtest loads the generated CRDs.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Test outline first
The test cases are written as a plain-English tree before any body. Follow the
steps in order, every time a task adds or changes specs. Target: $ARGUMENTS (the packages
to outline; empty means the whole repository).
1. Read the behaviour
- Read what defines the behaviour: the section of
docs/v3/spec.mdordocs/v3/status.md, or the walkthrough underdocs/v3/. - Read the package's
*_test.goto reuse itsDescribestructure and helpers. - Never invent behaviour. When the spec is silent or ambiguous, decide: what the kubelet
does first, then the most literal reading of
docs/v3/. Send each such decision to the coordinator and list it in the pull request description, one line each.
Suites live next to the code: one suite_test.go per package (envtest bootstrap, loads the
CRDs from config/crd/bases/) and *_test.go files beside the sources. Ginkgo and Gomega
only.
2. Write the tree with pending specs
Describe / Context name the object and the situation. Each case is a PIt, or a
PEntry inside a DescribeTable, with an empty body.
- One behaviour per string, present tense, the observable outcome.
- No implementation detail:
"sets Ready to False when the destination registry is unreachable", not"calls probe()". A case that would break if the code were reorganised without changing what the user sees tests an implementation detail: drop it. - A test exercises a behaviour, not a value (see
tests.md): no spec that reads a literal back. In envtest and e2e, one spec per rule rather than per verb, kind or field; in a unit suite, oneEntryper distinct input of a mapping or a parser. - Add the stubs the outline needs to compile (a type, a function returning its zero value), nothing more.
- A concurrency primitive (a limiter, a queue, a timer-driven wait) gets these cases from the start, each a real bug a later review found otherwise: the cancellation of the head, of a waiter in the middle and of the tail; 2 cancellations in a row; a waiter that wakes late; a config reload during the wait, and between reading the value and arming the wait; an interval or a limit dropping to 0.
- Include the PR's e2e cases, as empty
PItspecs undertest/e2e/:spec-reviewerchecks them with the rest. Their bodies come in one lasttestcommit once the PR is ready (e2e-spec): the suite is slow and runs once.
var _ = Describe("ImageMirror", func() {
Context("when the destination registry is unreachable", func() {
PIt("sets Ready to False with reason Unreachable", func() {})
PIt("retries without blocking the other images", func() {})
})
DescribeTable("destination path", func(path string) {},
PEntry("accepts a path with a trailing slash", "registry.tld/mirror/"),
PEntry("rejects a path carrying a tag", "registry.tld/mirror:latest"),
)
})3. Show the outline and go on
task test-outline -- <path> # the whole tree of the package
task test-outline DIFF=origin/main -- <path> # only the cases added and removed since mainThe example above prints:
# internal/controller/kuik/imagemirror_controller_test.go
ImageMirror
when the destination registry is unreachable
- sets Ready to False with reason Unreachable [pending]
- retries without blocking the other images [pending]
destination path
- accepts a path with a trailing slash [pending]
- rejects a path carrying a tag [pending]and with DIFF=origin/main, one line per case prefixed by + (added) or - (removed):
+ ImageMirror / when the destination registry is unreachable / sets Ready to False with reason Unreachable [pending]Before showing it, hand the outline and the spec section it covers to the spec-reviewer
sub-agent. Fix the cases it reports as missing or not in the spec; where the spec is
unclear, decide as in step 1.
Paste the output in the session's report, each top-level Describe group preceded by one line naming
the spec section it covers, with its GitHub link:
Covers docs/v3/status.md, "Conditions and their reasons": https://github.com/enix/kube-image-keeper/blob/main/docs/v3/status.md#conditions-and-their-reasonsA pull request stays issue-sized, about 30 specs at most. When the outline holds more, as an
epic (a feature too large for one review) does, cut it into such pull requests,
each mergeable on its own (main stays coherent, nothing is half-wired), each with its
docs and, last, its e2e specs. The issues of an epic are grouped under the GitHub
milestones of the release: its beta, then its GA.
Then go on to step 5 at once: the outline and the cut are reported, not waited on. The user reads them in the report and stops the session if a case or the cut must change.
The outline may be committed as a WIP test(<scope>): outline ... commit. It is squashed
into the first test commit of step 5.
4. Iterate on the strings
When the user asks for changes, apply them to the strings, and to the bodies already written, then show the outline again and go on.
5. Fill the bodies, before any implementation
Keep a todo list with Claude Code's task tools for the pull request,
one task per step of the plan (each outline group, each test/feat pair, the docs, the
e2e specs, each step of the pull-request skill), updated as
it goes. A list that grows too long is the sign the pull request must be cut further.
The session that owns the pull request hands the checked outline to one implementer
agent, which writes the bodies and the code; a reviewer agent reviews each feat commit
as it lands (0014).
Cut the outline into components by the code each feat commit changes, not by test layer:
each component names the files its feat commit modifies. A spec that needs no code of its
own (an earlier component already makes it pass) goes in the test commit of the component
whose feat turns it green, never in a test commit of its own, which would be green from
the start. e2e specs are the exception: their cases are in the outline from step 2, and
their bodies come in one last test commit, once the pull request is ready
(e2e-spec).
Work one component at a time, in 2 commits:
test(<scope>): ...: turnPItintoIt(PEntryintoEntry) and write the full bodies against the stubs. The specs fail at this commit, as expected;task lint-fixpasses.feat(<scope>): ...(orfix(<scope>): ...for a bug, with itsIntroduced-by:line, seetests.md): the implementation that turns exactly those specs green. It touches no*_test.gofile and no test helper package.
Then the next component. git log --stat must show every test file added by a test
commit and left alone by the feat commits: the reviewer checks it.
- Never rename a string while filling. A rename goes back to step 3.
- Never edit a test to make it pass. A test that contradicts
docs/v3/or cannot be written as stated is reported to the user with the section it relies on. It changes only with the user's approval, in its owntestcommit. - When a review (
reviewer, human, CodeRabbit) finds a bug the outline missed in code a commit of this branch adds, its regression spec is afixup!of thetestcommit of that component, and the fix afixup!of itsfeatcommit: the history keepstest(red) thenfeat(green). Neither waits for approval (tests.md). - A bug in code no commit of the branch owns is still test first: a regression pair on top
of the branch,
test(<scope>): add regression specs for <what>(red; a 2 or 3 line body names the review that found the bug) then thefix(<scope>)commit that turns it green. A bug-fix pull request is the same pair. Run the case alone, then the package:
go test ./<pkg> -v -ginkgo.focus '<It text>' go test ./<pkg>- Run
task manifestsfirst when a type changed: envtest loads the generated CRDs. - A plain
go teston an envtest suite finds the binaries in the main checkout'sbin/k8s/, shared by every worktree, only aftertask setup-envtest(or anytask test) has run once.
6. Before handing back
- No
PIt/PEntryleft unless the user agreed to keep it. task lint-fix.task test-outline DIFF=origin/mainonce more, and put its output in the report.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

