snap-forge ยท diff
git:20260916.b45a17a to git:20261015.19e4b4b
32 added, 38 removed. Audit A to A.
---
name: snap-forge
description: >
- Use when meaningful feature, bug-fix, or refactor work must be implemented in
- a repository with established tests, even when TDD is not requested; also use
- for explicit TDD, red-green-refactor, or test-first work.
+ Use when implementing a feature, bug fix, or refactor in a repository
---
- ## Invocation
-
- Syntax: `/skill:snap-forge [help] [branch[=name]] [worktree[=path]]`
-
- Bare keys mean `true`. `help` prints usage and stops. Unsafe unknown arguments stop with usage.
-
- ## Args
-
- | Key | Values | Default | Effect |
- | --- | --- | --- | --- |
- | `help` | bool | false | print usage; do not execute |
- | `branch` | bool/text | false | derive a branch or use the supplied name |
- | `worktree` | bool/text | false | derive a worktree path or use the supplied path |
-
- ## Routes
-
- | Selector | Workspace |
- | --- | --- |
- | default | current checkout and branch |
- | `branch` | requested or derived branch in the current checkout |
- | `worktree` | isolated worktree with a derived branch |
- | `branch` + `worktree` | requested branch in the requested or derived worktree |
+ Build the request one behavior at a time with red-green-refactor, testing only what earns a test:
- A direct implementation request or manual invocation authorizes relevant edits, tests, and commits. Otherwise ask before mutation. Branch and worktree creation require the corresponding explicit selector.
+ ```
+ checkout = current # branch or worktree only when asked
+ keep unrelated changes untouched
+ behaviors = split(request) # ask only if a gap changes observable behavior or the public interface
- ## Workflow
+ for b in behaviors:
+ if worth_test(b) and testable(b):
+ red(b) # one test; fails because b is missing, not setup
+ green(b) # smallest change that passes
+ elif worth_test(b):
+ agree verification with user; change
+ else:
+ change; verify with existing checks or observation
+ commit(b) # one Conventional Commit
+ refactor() # while green; separate commit
- 1. **Scope.** Reuse current context and fetch cited sources only when needed. Inspect relevant code, tests, interfaces, ADRs, and domain language. Turn acceptance into an ordered behavior list.
- Apply the test threshold in [`references/testing.md`](references/testing.md) to each behavior. Ask only when a missing decision changes observable behavior or the public interface. Use [`references/design.md`](references/design.md) when the test seam is unclear.
+ run checks scoped to the change; read the diff
+ done = every behavior verified and committed, scoped checks pass
- 2. **Workspace.** Prepare the selected route before editing. Preserve unrelated working-tree changes; ask one scope question when relevant and unrelated edits cannot be separated confidently.
+ worth_test(b) = owned(b) and a plausible regression fails it and types, linters, inspection miss it
+ # never: coverage, declarations, wiring, constants, trivial accessors, third-party behavior
+ ```
- 3. **Vertical loop.** Apply the test threshold per behavior; one work item may mix direct and red-green cycles. Complete one behavior before starting the next.
- - **DIRECT:** below the test threshold, make the smallest change and verify it with existing checks or direct observation.
- - **RED:** for test-worthy behavior, write one public-interface test and confirm it fails for the intended reason.
- - **GREEN:** make the smallest implementation that passes; run the targeted test and relevant checks.
- - **COMMIT:** create one atomic Conventional Commit for the completed behavior.
+ Tests
- 4. **Refactor.** Stay green. When the work exposes duplication, a shallow seam, or awkward coupling, use [`references/design.md`](references/design.md), refactor in small verified steps, and commit material refactoring separately.
+ - one behavior, public interface, survives refactors
+ - extend the existing suite first
+ - real owned code; doubles only at network, time, randomness
+ - expected values derived independently of the code under test
+ - real boundaries; no test-only production seams
- 5. **Verify.** Run the relevant broader checks, inspect the final diff, and report behaviors delivered, commands run, commits, and blockers.
+ Design
- Completion: every selected behavior has proportionate evidence, relevant checks pass, unrelated work is untouched, and each completed behavior is committed.
+ - narrow interface, deep implementation
+ - dependencies injected at boundaries
+ - explicit inputs, explicit results
+ - `refactor()`: duplication, shallow pass-throughs, mixed-purpose functions, primitive-heavy contracts