@groupby/ai-dev 0.4.2 → 0.5.1

package/teams/snpd/skills/tdd-implement/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: tdd-implement
+description: Use when the user invokes `/tdd-implement` (or asks to "implement this plan", "TDD this plan", "build the plan"). Reads an approved plan file from `.claude/artifacts/` (typically a `*-plan.md` produced by /draft-plan), creates a feature branch, implements the plan phase-by-phase using strict TDD (failing tests first, then green), commits each phase locally, then squashes into one commit on user approval. Updates the plan file with implementation-details and post-mortem sections (after approval). Never pushes, never creates a PR. Only runs when explicitly invoked — do NOT auto-trigger on the words "implement" or "TDD".
+---
+
+# tdd-implement
+
+Implement an approved plan with strict, phase-bound TDD. Produce a single
+squashed commit on a feature branch. Update the plan doc with what
+happened. Stop before push.
+
+## Inputs
+
+- **Plan file** — typically `.claude/artifacts/{KEY}_{slug}-plan.md`. The
+  user may pass it explicitly or by ticket key (`/tdd-implement S4R-10559`).
+- **If no argument is given:** list all `*-plan.md` files in
+  `.claude/artifacts/` with last-modified dates and ask which to implement.
+- **If no matching plan exists,** stop and tell the user to run
+  `/draft-plan` first. Do not invent a plan.
+
+## Workflow
+
+### 1. Read the plan end-to-end
+
+Read the entire plan file. Pay attention to:
+
+- **Goal** and **Approach** — the chosen direction.
+- **Affected areas** — files / modules to change or conform to.
+- **Sequencing** — the phases. This drives the TDD loop.
+- **Test strategy** — which test surfaces to extend.
+- **Risks & open questions** — flag any unresolved blockers.
+- **Decisions during planning** — constraints baked in.
+
+If any Risk or Open Question is unresolved and would block implementation,
+stop and surface it to the user before doing anything else.
+
+### 2. Load repo conventions and architecture
+
+Before writing any test or code, read these if they exist:
+
+- `docs/conventions.md` — code style, testing approach, API/migration
+  rules, commit conventions.
+- `docs/architecture.md` — package layout, domain model, cross-cutting
+  concerns.
+
+If neither file exists, fall back to:
+
+- `CLAUDE.md` / `AGENTS.md` at the repo root.
+- The plan file alone.
+- Top-level `README.md`.
+
+State explicitly to the user which sources informed the implementation.
+Skipping this step is the most common reason produced code does not match
+the repo.
+
+### 3. Pre-flight
+
+#### 3a. Detect the default branch
+
+Do **not** assume `main`. Detect dynamically:
+
+1. Try `git symbolic-ref --short refs/remotes/origin/HEAD` → strip the
+   `origin/` prefix.
+2. If that fails, try `git config init.defaultBranch`.
+3. If both fail, list local branches and ask the user which is the
+   default.
+
+Confirm the detected name with the user once before using it
+(`"Default branch detected as 'main' — correct?"`). Use this value
+everywhere `main` appears below.
+
+#### 3b. Working tree and current branch
+
+- Run `git status`. If there are uncommitted changes, stop and ask the
+  user how to proceed (stash / commit / abort).
+- Run `git rev-parse --abbrev-ref HEAD`. If `HEAD` is **not** the default
+  branch, ask:
+  > *"You're currently on branch `{current}`. Branch from `{default}`
+  > (recommended) or from `{current}`?"*
+
+#### 3c. Resume check
+
+The user may be re-running `/tdd-implement` after an interrupted session.
+Check whether a branch matching the conventional name already exists:
+
+- Derive ticket key from the plan filename and the default branch name
+  `{KEY}-{slug}`.
+- If `git rev-parse --verify {KEY}-{slug}` succeeds, **the branch
+  already exists**. Inspect its commit log:
+  - If it has commits matching `{KEY}: phase {N}…`, ask:
+    > *"Branch `{KEY}-{slug}` already exists with phases 1–{N} committed.
+    > Resume from phase {N+1}, restart from scratch, or cancel?"*
+  - On `resume`: check out the branch, skip ahead to phase {N+1} in the
+    phase loop.
+  - On `restart`: ask for confirmation, then delete the branch
+    (`git branch -D`) and re-create it. **Confirm before deleting.**
+  - On `cancel`: stop.
+- If the branch does not exist, proceed.
+
+#### 3d. Create the branch (if not resuming)
+
+- Default branch name: `{KEY}-{slug}` where `{slug}` is from the plan
+  filename (e.g. `S4R-10559-ai-adoption-runbook`).
+- Ask:
+  > *"Branch name `{KEY}-{slug}` look good, or do you want a different name?"*
+- Create and check out the branch from the previously-confirmed base
+  (the default branch, or the user's chosen base from step 3b).
+
+### 4. Phase loop (strict TDD per phase)
+
+For each phase in the plan's Sequencing section, in order:
+
+#### 4a. Write failing tests for this phase
+
+- Add tests covering the behavior in scope for this phase. Follow the
+  conventions in `docs/conventions.md` (testing section).
+- Run the test suite and confirm the new tests **fail for the right
+  reason** (compile error or assertion failure that maps to missing
+  behavior, not a setup mistake).
+- Commit locally:
+
+  ```text
+  {KEY}: phase {N} tests — <short phase title>
+  ```
+
+#### 4b. Implement until green
+
+- Make the minimum changes that turn the failing tests green.
+- Follow conventions in `docs/conventions.md` and patterns in
+  `docs/architecture.md`.
+- Run the full test suite. All tests (new and pre-existing) must pass
+  before this phase is considered complete.
+- Refactor if needed; tests must stay green.
+- Commit locally:
+
+  ```text
+  {KEY}: phase {N} — <short phase title>
+  ```
+
+#### 4c. Move to next phase
+
+Repeat 4a/4b until all phases are complete.
+
+### 5. Discovery triage during implementation
+
+Discoveries happen. Classify each one and act accordingly:
+
+- **Trivial** — typo, missing import, obvious local refactor, name clash
+  with no design implication. Resolve silently. Mention briefly in the
+  implementation-details section at the end.
+- **Plan-affecting** — a new touch point not in the plan, a wrong file
+  path in the plan, a missing test surface, a sequencing change.
+  **Pause.** Tell the user what was found, propose how to adjust the
+  approach, wait for approval before proceeding. Capture the resolution
+  for the post-mortem.
+- **Spec-affecting** — an acceptance criterion cannot be met as written,
+  ambiguity in the spec surfaces, scope appears to expand. **Stop.**
+  Do not proceed without explicit user direction. The plan may need to
+  be revised via `/draft-plan` again, or the spec may need to be
+  revisited. Capture the issue for the post-mortem.
+
+When in doubt between trivial and plan-affecting, treat it as
+plan-affecting and ask. Silent drift from the plan is the failure mode
+to avoid.
+
+### 6. Verification gate
+
+Before claiming implementation is complete, run the project's full check.
+Detect the right command — do **not** assume Gradle:
+
+1. If `docs/conventions.md` or `CLAUDE.md` specifies a "full check" command,
+   use it.
+2. Otherwise detect from repo files (first match wins):
+   - `./gradlew` exists → `./gradlew check`
+   - `pom.xml` exists → `mvn verify`
+   - `package.json` exists → `npm test` (or `pnpm test` / `yarn test`
+     if the matching lockfile is present)
+   - `Cargo.toml` exists → `cargo test`
+   - `go.mod` exists → `go test ./...`
+   - `pyproject.toml` / `setup.py` / `tox.ini` exists → `pytest` (or
+     `tox`, or `python -m unittest` — pick the one the repo's CI uses
+     if visible)
+3. If none of the above matches, ask the user which command to run.
+
+Capture and quote the actual command output in your message to the user.
+Do not claim "passing" without evidence.
+
+If anything fails, fix and re-run. If a failure is environmental (Docker
+not running, port in use, missing tool), surface it — don't paper over.
+
+### 7. Propose plan update (NOT yet written)
+
+Once verification passes, draft the two new sections in chat (do not yet
+write to file):
+
+```markdown
+## Implementation Details
+
+<What was actually built, file by file or area by area. Include:
+- Files added / modified / removed (high-level — no line ranges).
+- Deviations from the plan and why (link to discovery triage if any).
+- Any trivial discoveries that didn't warrant pausing.
+- Final test surface — what was added, what passed.
+- Commands run to verify (the detected verification command, etc.) with results.>
+
+## Post-Mortem
+
+<Reflective notes for the team. Include:
+- What surprised you (good or bad).
+- What the plan got right; what the plan missed.
+- Patterns / conventions that should be documented (suggest, don't write).
+- Follow-ups worth doing in a future ticket (suggest, don't open them).
+- Anything worth promoting into `docs/decisions.md` (suggest, don't
+  write — decisions are append-only and human-curated even when the
+  /docs-init skill adds them).>
+```
+
+Present both sections in chat. Ask:
+> *"Approve these sections to be appended to the plan file? Reply
+> `approve` to write them, or tell me what to change. Once written I
+> will offer to squash the implementation commits."*
+
+### 8. Write the plan update on approval
+
+- Append both sections verbatim to the plan file. Do **not** rewrite
+  prior sections.
+- Preserve the existing `> **Scope:**`-style header if the plan has one.
+- The plan file is gitignored (`.claude/artifacts/` is excluded), so this
+  edit produces no commit. Mention this so the user knows the change is
+  local-only.
+
+### 9. Squash and finish
+
+Ask the user:
+> *"Squash the {N} phase commits into a single `{KEY}: <plan headline>`
+> commit, or keep the per-phase history? Reply `squash` (default) or
+> `keep`."*
+
+On `squash`:
+
+1. Identify the branch base via `git merge-base HEAD {default-branch}`,
+   using the default-branch name detected in step 3a.
+2. `git reset --soft <branch-base>` — collapses all phase commits into
+   the working stage.
+3. Create one fresh commit:
+
+   ```text
+   {KEY}: <plan headline>
+
+   <2-4 line terse summary of what changed. No bullet lists, no auto-
+   generated file inventories, no boilerplate footer.>
+   ```
+
+4. Show the final commit (`git log -1 --stat`) so the user can review.
+
+On `keep`: leave the per-phase history intact.
+
+### 10. Stop
+
+After the squash (or after the `keep` choice), the skill is done. Print
+a single closing line:
+
+> *"Branch `{branch}` is ready. Plan file updated at `<path>`. Push and
+> open a PR when you're ready — I will not do that automatically."*
+
+Do **not**:
+
+- `git push` (even with `--dry-run`).
+- Create a PR via `gh` or any other tool.
+- Open follow-up tickets.
+- Edit `docs/decisions.md`, `docs/operations.md`, or any doc the
+  post-mortem suggested updating — those are user actions.
+- Start another implementation cycle ("want me to do the follow-ups now?").
+
+## Hard rules
+
+- **Never assume the default branch is `main`.** Detect it in step 3a and
+  confirm with the user before using it.
+- **Strict TDD per phase, never per-skill batch.** Tests first, green
+  before moving on. Do not write tests for phase N+1 before phase N is
+  green.
+- **Every commit message starts with `{KEY}:`.** Per the repo convention
+  in `docs/conventions.md`.
+- **Never push, never create a PR.** These are user actions only.
+- **Never bypass verification.** The detected verification command (step 6)
+  must pass before the implementation is declared complete. No
+  `--no-verify`, no skipped tests, no commented-out failing assertions.
+- **Never modify the spec file or prior plan sections.** Plan updates
+  are appended (Implementation Details + Post-Mortem). Specs are
+  audit records.
+- **Never auto-act on post-mortem suggestions.** Suggestions are for the
+  user. The skill does not open tickets, write decisions entries, or
+  update docs based on the post-mortem.
+- **Squash via `git reset --soft`, not interactive rebase.** No editor,
+  no risk of dropping commits.
+- **Do not start implementation without an approved branch name.** Even
+  if the user invoked the skill, confirm the branch name once before
+  creating it.
+
+## Common mistakes
+
+- Treating "/tdd-implement" invocation as authorization to skip the
+  branch-name confirmation.
+- Hardcoding `main` instead of detecting the default branch. Some repos
+  use `master`, `develop`, or `trunk`.
+- Skipping `docs/conventions.md` and `docs/architecture.md` in step 2.
+  Plans reference them; they are not duplicated in the plan.
+- Re-creating an existing branch on resume without asking. Phases
+  already committed there are user work.
+- Writing all tests up-front across all phases. Phase-bound is the rule.
+- Resolving a plan-affecting discovery silently because it "seemed
+  small". Silent drift compounds — ask.
+- Claiming verification passed without quoting the actual command output.
+- Pushing or opening a PR on the user's behalf.
+- Editing `docs/` based on post-mortem suggestions. The skill suggests,
+  the user acts.
+- Squashing without showing the final commit and message for review.
+- Forgetting the `{KEY}:` prefix on per-phase commits because "they'll
+  be squashed anyway." If the user picks `keep`, those commits become
+  history.