diff --git a/README.md b/README.md index dc4a5b2..7b10c28 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,14 @@ than assuming the delegate can fetch it itself. rebase conflict by tracing each side's intent; never `--abort`. - `tdd` -- red-green-refactor test-driven development, one vertical slice at a time, at pre-agreed seams. +- `writing-implementation-plans` -- turn settled requirements into + self-contained, dependency-aware tasks that memoryless delegates can + execute and verify without the originating conversation. +- `receiving-code-review` -- verify incoming review findings against the + actual codebase and spec before accepting, rejecting, or implementing them. +- `finishing-development-branches` -- verify the exact branch tip, confirm + its base, and require an explicit integration choice before merge, Gitea + push/PR, or cleanup. ## Provenance @@ -105,6 +113,8 @@ each skill's frontmatter: - [Mte90/linus-torvalds-skill](https://github.com/Mte90/linus-torvalds-skill) (CC0-1.0) - [mattpocock/skills](https://github.com/mattpocock/skills) (MIT) - [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) (MIT) +- [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) (MIT; + evaluated, no skill retained) ## Vetting external skills @@ -125,4 +135,4 @@ When a real, non-obvious pattern or gotcha comes up more than once, write it down here rather than re-discovering it next time. Keep each skill focused on one concern, include the *why* (not just the *what*) so future edge cases can be judged sensibly, and prefer concrete confirmed -incidents over generic advice. \ No newline at end of file +incidents over generic advice. diff --git a/skills/finishing-development-branches/SKILL.md b/skills/finishing-development-branches/SKILL.md new file mode 100644 index 0000000..d027f85 --- /dev/null +++ b/skills/finishing-development-branches/SKILL.md @@ -0,0 +1,113 @@ +--- +name: finishing-development-branches +description: Use after implementation is complete and before merging, pushing, opening a Gitea pull request, or cleaning up a feature branch or worktree. +license: MIT +source: https://github.com/obra/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md +--- + +# Finishing Development Branches + +Completion and integration are different decisions. A green feature branch +does not authorise merging, pushing, deleting branches, or removing worktrees. +Verify the exact tree, identify its provenance, then let the user choose the +integration action. + +## 1. Establish the state + +From the feature workspace, record: + +```bash +git status --short +git branch --show-current +git rev-parse HEAD +git rev-parse --show-toplevel +git rev-parse --git-dir +git rev-parse --git-common-dir +git remote -v +``` + +Determine the intended base branch from the brief, branch upstream, merge +base, or conversation. If it is not confirmed, ask. Do not assume `main`. + +Stop if the tree contains unexplained changes. They may belong to the user or +another delegate; do not stage, discard, or fold them into the integration. + +## 2. Verify the branch tip + +Run the project’s required targeted and full regression checks on the current +`HEAD`. Read their actual output. For higher-risk changes, run the relevant +end-to-end path as required by `verification-before-completion`. + +Also inspect what will integrate: + +```bash +git log --oneline ..HEAD +git diff --check ...HEAD +git diff --stat ...HEAD +``` + +If a check fails, report the failure and stop. Do not offer integration of a +known-red branch. + +## 3. Present the integration choices + +Report the confirmed base, branch/commit, test evidence, and whether this is a +linked worktree. Then offer only applicable choices: + +1. Merge locally into the confirmed base. +2. Push the feature branch and open a Gitea pull request. +3. Keep the branch and workspace unchanged for later review. + +Wait for the user’s choice. Do not infer permission to push or merge from a +request to implement or commit. Never offer deletion as routine cleanup. + +## 4. Execute only the chosen action + +### Merge locally + +Before pulling or contacting a remote, confirm that updating the base from the +remote is wanted. From the primary checkout: + +```bash +git switch +git merge +``` + +Do not use a strategy flag merely to avoid conflicts. If conflicts occur, +follow `resolving-merge-conflicts`; never abort the merge/rebase. Re-run the +full verification suite on the merged tree because the result is a different +tree from the tested feature tip. + +### Push and create a Gitea pull request + +Confirm the remote and branch names before pushing. Never force-push to solve +a rejection; inspect the remote divergence and ask if rewriting remote history +would be required. Follow repository/Gitea templates and report the pull +request URL. Keep the feature workspace for review fixes. + +### Keep as-is + +Report the branch name, commit, and full workspace path. Make no cleanup +changes. + +## 5. Cleanup is separately authorised + +Remove a linked worktree or delete a branch only after its work is safely +integrated, or after the user explicitly asks to discard it. Before a discard, +show the exact branch, worktree path, and commits that would become +unreferenced; require an explicit confirmation naming those targets. + +Never clean unrelated or merely “stale-looking” worktrees. Never use +force-deletion for normal cleanup. After any authorised cleanup, verify with +`git worktree list` and `git branch --list` and report what was removed. + +## Stop conditions + +Stop and preserve all state when: + +- tests or merged-result verification fail; +- the base branch is uncertain; +- the remote has diverged; +- conflicts are unresolved; +- the tree contains unexplained changes; +- the requested action would delete or rewrite work without explicit consent. diff --git a/skills/receiving-code-review/SKILL.md b/skills/receiving-code-review/SKILL.md new file mode 100644 index 0000000..938882e --- /dev/null +++ b/skills/receiving-code-review/SKILL.md @@ -0,0 +1,89 @@ +--- +name: receiving-code-review +description: Use when acting on code-review findings from a human or delegate, especially when feedback is ambiguous, technically questionable, or may conflict with the specification or existing behavior. +license: MIT +source: https://github.com/obra/superpowers/blob/main/skills/receiving-code-review/SKILL.md +--- + +# Receiving Code Review + +Review feedback is a claim to investigate, not a patch queue to apply blindly. +The reviewer may have missed codebase context; the implementer may be biased +toward defending their own work. Resolve both risks with evidence. + +## Triage the complete review first + +For every finding, record: + +- exact file/line and the claimed failure; +- severity and whether it blocks the stated requirements; +- the reviewer’s proposed fix, if any; +- whether the finding is clear, verified, disputed, or needs a decision. + +Read all findings before editing. Items can depend on each other, and fixing a +clear symptom before understanding a related architectural concern can create +rework. + +## Verify against this codebase + +For each material finding: + +1. Restate the falsifiable claim: what input or state should produce what bad + result? +2. Inspect the cited code plus its callers, tests, compatibility constraints, + and relevant specification. +3. Reproduce the problem or add the cheapest check that distinguishes a real + defect from a false positive. +4. Decide whether the proposed fix addresses the root cause without breaking + existing behavior, tenant isolation, platform support, or scope. + +For multi-tenant changes, explicitly test a cross-tenant negative case; a +query that returns the expected row for one tenant does not prove RLS safety. +For WordPress or infrastructure changes, verify the actual runtime convention +instead of substituting a generic framework preference. + +If a finding cannot be verified with available access or artifacts, say +exactly what evidence is missing. Do not silently convert uncertainty into an +implementation decision. + +## Resolve conflicts before editing + +- If the finding is unclear, ask one concrete question and do not guess at the + requested behavior. +- If it conflicts with the approved spec or a prior user decision, present the + conflicting texts and ask which governs. +- If it requests unused “professional” machinery, search for actual callers + and requirements first; reject scope growth that has no consumer. +- If it is technically wrong, push back with code, tests, or runtime evidence. + Do not comply merely because the reviewer sounds confident. +- If it is correct, fix it without performative agreement. State the verified + problem and the change. + +## Implement and close findings one at a time + +Order work by security/data-loss defects, other blocking correctness defects, +then non-blocking improvements. For each accepted finding: + +1. Create or identify a check that fails for the reported problem. +2. Apply the smallest in-scope fix. +3. Re-run the targeted check and relevant regression tests. +4. Record the evidence and mark only that finding resolved. + +Do not let the implementer’s self-review close the loop. A fresh reviewer (or +the lead model) must inspect the fix diff, and `verification-before-completion` +still applies before reporting the review resolved. + +## Response format + +Keep the response technical: + +```text +Finding: +Verdict: accepted | rejected | needs decision | unverified +Evidence: +Action: +Verification: +``` + +Avoid gratitude, defensiveness, or automatic agreement. The useful output is +a traceable decision backed by evidence. diff --git a/skills/writing-implementation-plans/SKILL.md b/skills/writing-implementation-plans/SKILL.md new file mode 100644 index 0000000..f0f8c24 --- /dev/null +++ b/skills/writing-implementation-plans/SKILL.md @@ -0,0 +1,113 @@ +--- +name: writing-implementation-plans +description: Use when requirements are settled and a multi-step change needs an implementation plan that memoryless delegates can execute without access to the originating conversation. +license: MIT +source: https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md +--- + +# Writing Implementation Plans + +A plan is an executable handoff, not a summary of intent. The worker may be a +fresh CLI delegate with no conversation history, and individual tasks may be +assigned out of order. If the plan leaves a choice implicit, the worker will +have to invent it. + +## Before writing tasks + +1. Read the settled spec or requirements and inspect the actual code paths, + tests, project instructions, and established patterns involved. +2. Resolve contradictions and material unknowns before planning. Marking them + `TBD` only moves the design decision to a less-informed delegate. +3. Map every file to create or modify and give each one a clear + responsibility. Avoid unrelated restructuring. +4. Split work into independently testable vertical slices. Fold setup, + migrations, wiring, and documentation into the slice that needs them; + don't create standalone tasks that leave the system unusable. +5. Identify shared files and state. Tasks that edit the same bootstrap file, + schema, migration sequence, or live environment are sequential unless the + design removes that collision. See `parallel-delegate-shared-files`. + +## Plan header + +Start with: + +```markdown +# Implementation Plan + +**Goal:** + +**Architecture:** + +**Stack and environment:** + +## Global constraints + +- + +## Verification + +- +``` + +Copy exact values from the requirements. For multi-tenant work, state the +tenant/RLS invariants explicitly; never let a worker infer them from nearby +code. For remote or production-adjacent work, state the exact host/jail, +whether mutation is authorised, and how secrets must be read without being +printed. + +## Task contract + +Each task must stand alone: + +```markdown +### Task N: + +**Depends on:** + +**Files:** +- Create: `exact/path` +- Modify: `exact/path` — +- Test: `exact/path` + +**Interfaces:** +- Consumes: +- Produces: + +**Requirements:** +- + +**Steps:** +- [ ] Write the failing test for . +- [ ] Run ``; expect . +- [ ] Implement the smallest change that passes it. +- [ ] Run ``; expect . +- [ ] Run ``; expect no regressions. +- [ ] Commit only this task's files with ``. + +**Report:** +``` + +Write exact commands and concrete expected signals. Include code or +pseudocode only where it removes a real ambiguity; don't turn the plan into a +second implementation. When a task brief will be extracted from the plan, +repeat its binding constraints instead of saying “same as above.” + +## Self-review before delegation + +- Trace every requirement to a task and every task to the goal. Remove gaps + and scope creep. +- Search for placeholders and vague steps: `TBD`, `TODO`, “handle errors,” + “add validation,” “write tests,” “similar to Task N.” Replace each with an + explicit decision or action. +- Check that interface names and types match across tasks. +- Check ordering: a task must not consume an artifact that does not exist yet. +- Check concurrency: no parallel tasks may edit the same file or mutate the + same shared environment. +- Check verification: every claimed outcome has a command or observation that + could prove it false. +- Have the user approve material architectural or scope decisions before + implementation begins. + +When dispatching tasks, still apply `delegate-brief-writing`: the extracted +task plus relevant global constraints, confirmed facts, credentials handling, +verification, and report contract form the self-contained brief.