@groupby/ai-dev 0.5.14 → 0.5.16

package/teams/brain-studio/skills/tdd-implement/SKILL.md

@@ -0,0 +1,278 @@
+---
+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 `.ai/tasks/{KEY}/plan.md`, 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. Appends a `## Deviations` and `## Post-Mortem` section to the local (gitignored) plan file. 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. This is **Step 4** of the AI-assisted
+development workflow.
+
+## Inputs
+
+- **Plan file** — `.ai/tasks/{KEY}/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 `.ai/tasks/*/`
+  with last-modified dates and ask which to implement.
+- **If no plan.md exists** (no argument given and none found under
+  `.ai/tasks/*/`, or an explicit key/path was given but the file is missing):
+  do **not** guess or fabricate a plan, and do **not** implement anything
+  without one. Ask the user for a plan-file path, a ticket key, or to run
+  `/draft-plan` first — then stop and wait for the user's answer. This
+  approval gate is never skipped: implementation only proceeds against an
+  approved `plan.md`.
+
+## 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 code-generation skills
+
+Before writing any test or code, load these in order:
+
+1. Apply the `arch-context` skill to load baseline code conventions and any
+   additional architecture docs the plan's change types require (it owns the
+   Doc Routing Table and the conditional on whether `docs/architecture/`
+   exists in this repo).
+2. Load the `javascript` skill, then the `typescript` skill.
+3. Load the `react` skill (if `.tsx` files are involved).
+4. Load the `styled-components` skill (if `.styles.ts` files are involved).
+5. `.ai/patterns.md` (if it exists — check for relevant past solutions).
+
+State explicitly to the user which sources informed the implementation.
+
+### 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 `origin/`.
+2. If that fails, try `git config init.defaultBranch`.
+3. If both fail, ask the user.
+
+Confirm with the user once before using it.
+
+#### 3b. Working tree and current branch
+
+- `git status`. If uncommitted changes, stop and ask (stash / commit / abort).
+- Check current branch. If not on the expected feature branch, ask how to
+  proceed.
+
+#### 3c. Branch check
+
+The branch should already exist (created at workflow Step 2, after spec).
+Check for `<type>/{KEY}-{slug}`:
+
+- If the branch exists and is checked out — continue.
+- If the branch exists but is not checked out — switch to it.
+- If the branch does NOT exist — create it. Derive type from the Jira issue
+  type in `.ai/tasks/{KEY}/spec.md` (read it if present — do not fabricate
+  one if it's missing; ask the user for the issue type instead):
+  - Bug → `fix/`
+  - Story/Task → `feature/`
+  - Spike/Chore → `chore/`
+  - Or ask the user.
+- Use the slug from `.ai/tasks/{KEY}/spec.md` metadata, if present; otherwise
+  ask the user for the slug.
+- Confirm branch name with user before creating.
+
+#### 3d. Resume check
+
+If the branch already has implementation commits (matching
+`<type>(<scope>): phase N`), ask:
+
+> *"Branch has phases 1–{N} committed. Resume from phase {N+1}, restart,
+> or cancel?"*
+
+### 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.
+- Tests go in `test/unit/` and/or `test/integration/` (NOT co-located with src).
+- Use custom `render()` from `test-utils.tsx` for component tests.
+- Follow conventions from `docs/architecture/11-testing-strategy/`, if present.
+- Run the tests for this phase's surface: `yarn test:unit` and/or
+  `yarn test:integration` (whichever surfaces the phase touches).
+- Confirm new tests **fail for the right reason**.
+- Commit:
+  ```
+  test(<scope>): phase {N} tests — <short phase title> ({KEY})
+  ```
+
+#### 4b. Implement until green
+
+- Make the minimum changes that turn the failing tests green.
+- Follow loaded code-generation skills and architecture conventions.
+- All user-visible strings through `useLocalization()` / FormatJS.
+- Styled-components in `.styles.ts` with PascalCase exports.
+- Redux state via `useAppSelector` / `useAppDispatch`.
+- Path aliases: `@/` for imports from `src/`.
+- Run `yarn test` — this runs the **full** unit + integration suite, not just
+  this phase's tests, so it also guards against regressions in earlier phases.
+- All tests (new and pre-existing) must pass.
+- Refactor if needed; tests must stay green.
+- Lint and typecheck run only at the final verification gate (step 6),
+  not per phase.
+- Commit:
+  ```
+  <type>(<scope>): phase {N} — <short phase title> ({KEY})
+  ```
+  Where `<type>` matches the branch type (feat/fix/chore).
+
+#### 4c. Move to next phase
+
+Repeat 4a/4b until all phases are complete.
+
+### 5. Discovery triage during implementation
+
+| Category | Action |
+|----------|--------|
+| **Trivial** — typo, missing import, name clash | Fix silently. Note in the plan's `## Deviations` section. |
+| **Plan-affecting** — new touch point, wrong path, sequencing change | **Pause.** Tell user. Propose adjustment. Wait for approval. Append a `## Revision` section to `plan.md`, using the format defined in the `draft-plan` skill's "Plan Revision" section (Trigger / Change / Impact / Approved by). |
+| **Spec-affecting** — AC cannot be met, scope expands | **Stop.** Do not proceed without user direction. May need `/draft-plan` revision. |
+
+When in doubt → treat as plan-affecting and ask.
+
+### 6. User checkpoint
+
+After all phases are complete and verification passes, show:
+
+- Files changed (`git diff --stat` from branch base)
+- Verification output (lint + typecheck + test — all green)
+- Summary: what was done per phase
+
+User options:
+- `[ok]` → proceed to AI review (next workflow step)
+- `[check]` → user inspects manually, then `[ok]` / `[fix X]` / `[rethink]`
+- `[fix X]` → agent fixes, re-runs verification, shows result again
+
+### 7. Append Deviations + Post-Mortem to the plan
+
+Once the user accepts the checkpoint (`[ok]`), append two short sections to the
+**end** of `plan.md`. Append verbatim — never rewrite earlier sections.
+
+```markdown
+## Deviations
+
+<Only what was actually done outside or beyond the plan: unplanned touch
+points, corrected file paths, scope adjustments, trivial discoveries that
+changed nothing structurally. If nothing diverged, write "None".>
+
+## Post-Mortem
+
+<A brief reflection for reviewers: what the plan got right, what it missed,
+gotchas worth remembering. Keep it to a few bullets.>
+```
+
+- The `.ai/` folder is gitignored, so this edit produces **no commit** — it is
+  local-only and reaches the team later through the PR body (`/draft-pr` embeds
+  the plan under a `<details>` block).
+- There is **no** separate `history.md` — the plan is the single record.
+- If a `## Revision` section was added during implementation (step 5), leave it
+  in place; `## Deviations` complements it (Revision = approved mid-flight plan
+  change, in the `draft-plan` skill's format; Deviations = what actually
+  happened).
+
+### 8. Squash (on user request, typically after review)
+
+When the user is ready (usually after `/pr-review` passes):
+
+> *"Squash the {N} phase commits into one? Reply `squash` or `keep`."*
+
+On `squash`:
+
+1. `git merge-base HEAD {default-branch}` → find branch point.
+2. `git reset --soft <branch-base>` → collapse all commits.
+3. Create one commit:
+   ```
+   <type>(<scope>): <plan headline> ({KEY})
+
+   <2-4 line summary of what changed.>
+   ```
+4. Show `git log -1 --stat` for review.
+
+On `keep`: leave per-phase history intact.
+
+### 9. Stop
+
+After squash (or keep), print:
+
+> *"Implementation complete. Run `/pr-review` for the next step, or
+> `/draft-pr` if review is already done."*
+
+Do **not**:
+- `git push`
+- Create a PR
+- Open follow-up tickets
+- Edit docs based on discoveries (suggest in the plan's Post-Mortem, don't write)
+
+## Verification gate
+
+Run once after **all phases are complete** (before step 6 user checkpoint):
+
+```bash
+yarn lint && yarn typecheck && yarn test
+```
+
+This runs:
+- ESLint (Airbnb + TypeScript + React hooks + sonarjs + FormatJS)
+- TypeScript compiler (`tsc --noEmit`)
+- Unit tests (Jest + Testing Library)
+- Integration tests (Jest)
+
+All three must pass before declaring the implementation complete. This is a
+**final gate only** — per-phase checks run `yarn test` alone (step 4b), which
+already covers both unit and integration tests; lint and typecheck are
+deferred to this final gate.
+No `--no-verify`, no skipped tests, no commented-out assertions.
+
+**TDD watch mode:** For interactive development, recommend `yarn tdd` (runs
+unit + integration in parallel watch mode).
+
+## Hard rules
+
+- **Branch format:** `<type>/{KEY}-{slug}` — never bare KEY, never missing type prefix.
+- **Commit format:** `<type>(<scope>): <description> ({KEY})` — key in parentheses at end.
+- **Strict TDD per phase.** Tests first, green before moving on.
+- **Never push, never create a PR.**
+- **Never implement without an approved `plan.md`.** If none can be found, ask
+  the user — do not fabricate one and do not proceed without it.
+- **Never bypass verification.** Full `yarn lint && yarn typecheck && yarn test` must pass.
+- **Never modify the spec file.**
+- **Plan revisions are appended, not overwritten.**
+- **Squash via `git reset --soft`, not interactive rebase.**
+- **User checkpoint before declaring done.** Agent waits for explicit go-ahead.
+- **Load code-generation skills before writing code.** Do not rely on memory.
+
+## Common mistakes
+
+- Hardcoding `main` instead of detecting the default branch.
+- Creating branch as `{KEY}-{slug}` without the type prefix.
+- Writing commits as `{KEY}: ...` instead of `<type>(<scope>): ... ({KEY})`.
+- Running only `yarn test` without lint and typecheck.
+- Placing tests next to source files instead of in `test/unit/` or `test/integration/`.
+- Using raw CSS or inline styles instead of styled-components.
+- Using raw strings in JSX instead of FormatJS i18n.
+- Skipping the user checkpoint and jumping to squash.
+- Writing all tests up-front across all phases instead of phase-by-phase.
+- Silently resolving plan-affecting discoveries.
+- Pushing or opening a PR.
+- Implementing against a guessed or fabricated plan instead of asking the user
+  when no `plan.md` can be found.