spec-approach

Name: spec-approach
Author: eduwxyz

15stars1forks

How to install spec-approach?

eduwxyz/my-awesome-skills/spec-approach

$npx -y skills add eduwxyz/my-awesome-skills --skill spec-approach

Installs into the current project.

Summary

Add a refined ## Approach section to an existing feature spec.md before TDD executes it. Reads the spec, explores the codebase to ground the approach in real modules and patterns, proposes 2–3 alternatives when they exist, validates with the user, then appends ## Approach to

Files · 1

View on GitHub

SKILL.md

1	# Spec Approach
2
3	Take an existing feature spec and add the `## Approach` — the HOW that `tdd` needs to execute. Same file, append only.
4
5	## Skip spec-approach for
6
7	- Bug specs (output of `diagnose` — already contain `Root cause` and `Fix`).
8	- Trivial changes — single file, obvious extension of an existing pattern.
9	- Specs that already have `## Approach` — unless the user explicitly asks to revise.
10
11	If invoked in a skip case, recognise it and tell the user "this looks trivial / already approached — go straight to `tdd`". Do not write anything.
12
13	## Before you start
14
15	Identify the spec. A path or slug for an existing `spec/<slug>.md` must be given. If neither was provided, ask the user which spec — do not guess. Never operate without an explicit target.
16
17	Validate it. Read the file. It must contain `Goal`, `Behaviors`, and `Acceptance criteria`. If any are missing, abort and tell the user to run `interview-to-spec` first. Never try to fill in WHAT.
18
19	## The work
20
21	1. Read the spec. Internalise Goal, Behaviors, AC, OOS, Edge cases.
22	2. Explore the codebase. Find relevant modules, patterns, existing ADRs, similar features. The approach must be grounded in what is actually there — not invented.
23	3. Propose. State a recommended approach. If multiple paths are viable, show 2–3 with tradeoffs and recommend one.
24	4. Validate with the user. Ask one question at a time, only when judgment is required (which alternative? what's the priority?). Do not ask what the codebase can answer — read the codebase.
25	5. Append. Add `## Approach` to the same spec file.
26
27	## How to append (safety rules)
28
29	- Use `Edit`, not `Write`. Anchor on the last existing line or section of the spec; the new content is the anchor + `\n\n## Approach\n...`.
30	- Never create a new file.
31	- Never modify the WHAT sections above (Goal, Behaviors, AC, OOS, Edge cases). Touch only the bottom of the file.
32	- If the spec ends with a trailing newline, preserve it.
33
34	## The `## Approach` section
35
36	```markdown
37	## Approach
38	- Strategy. One paragraph describing how the work will be done end-to-end.
39	- Modules / files. Concrete paths to create or modify.
40	- Key decisions. The alternative considered and why this one. One bullet per decision.
41	- Schema / API changes. If any. Otherwise omit this bullet.
42	- Risks. Anything that might surprise us during execution. If none, omit this bullet.
43	```
44
45	Keep each bullet tight. The reader is `tdd` — it needs enough to execute, not a design doc.
46
47	## When `## Approach` already exists
48
49	Do not overwrite silently. Read the existing approach, then ask the user: "There's already an approach here. Want me to revise it, or is it still good?" Only edit if they confirm. When revising, replace the existing `## Approach` block via `Edit` — do not append a second one.
50
51	## Where this skill ends
52
53	The spec is now self-sufficient. `tdd` consumes it directly — Behaviors + Acceptance criteria become the test queue; Approach guides the implementation.

People who liked this also viewed

6 picks

Type

spec-approach

15stars1forks

View on GitHub

How to install spec-approach?

eduwxyz/my-awesome-skills/spec-approach

$npx -y skills add eduwxyz/my-awesome-skills --skill spec-approach

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Spec Approach
2
3	Take an existing feature spec and add the `## Approach` — the HOW that `tdd` needs to execute. Same file, append only.
4
5	## Skip spec-approach for
6
7	- Bug specs (output of `diagnose` — already contain `Root cause` and `Fix`).
8	- Trivial changes — single file, obvious extension of an existing pattern.
9	- Specs that already have `## Approach` — unless the user explicitly asks to revise.
10
11	If invoked in a skip case, recognise it and tell the user "this looks trivial / already approached — go straight to `tdd`". Do not write anything.
12
13	## Before you start
14
15	Identify the spec. A path or slug for an existing `spec/<slug>.md` must be given. If neither was provided, ask the user which spec — do not guess. Never operate without an explicit target.
16
17	Validate it. Read the file. It must contain `Goal`, `Behaviors`, and `Acceptance criteria`. If any are missing, abort and tell the user to run `interview-to-spec` first. Never try to fill in WHAT.
18
19	## The work
20
21	1. Read the spec. Internalise Goal, Behaviors, AC, OOS, Edge cases.
22	2. Explore the codebase. Find relevant modules, patterns, existing ADRs, similar features. The approach must be grounded in what is actually there — not invented.
23	3. Propose. State a recommended approach. If multiple paths are viable, show 2–3 with tradeoffs and recommend one.
24	4. Validate with the user. Ask one question at a time, only when judgment is required (which alternative? what's the priority?). Do not ask what the codebase can answer — read the codebase.
25	5. Append. Add `## Approach` to the same spec file.
26
27	## How to append (safety rules)
28
29	- Use `Edit`, not `Write`. Anchor on the last existing line or section of the spec; the new content is the anchor + `\n\n## Approach\n...`.
30	- Never create a new file.
31	- Never modify the WHAT sections above (Goal, Behaviors, AC, OOS, Edge cases). Touch only the bottom of the file.
32	- If the spec ends with a trailing newline, preserve it.
33
34	## The `## Approach` section
35
36	```markdown
37	## Approach
38	- Strategy. One paragraph describing how the work will be done end-to-end.
39	- Modules / files. Concrete paths to create or modify.
40	- Key decisions. The alternative considered and why this one. One bullet per decision.
41	- Schema / API changes. If any. Otherwise omit this bullet.
42	- Risks. Anything that might surprise us during execution. If none, omit this bullet.
43	```
44
45	Keep each bullet tight. The reader is `tdd` — it needs enough to execute, not a design doc.
46
47	## When `## Approach` already exists
48
49	Do not overwrite silently. Read the existing approach, then ask the user: "There's already an approach here. Want me to revise it, or is it still good?" Only edit if they confirm. When revising, replace the existing `## Approach` block via `Edit` — do not append a second one.
50
51	## Where this skill ends
52
53	The spec is now self-sufficient. `tdd` consumes it directly — Behaviors + Acceptance criteria become the test queue; Approach guides the implementation.

People who liked this also viewed

6 picks

Type