xiduzo/wtf / skills/wtf.implement-trace
wtf.implement-trace
VerifiedThis skill should be used when a developer is ready to implement, resume, or continue a GitHub Trace issue — for example "implement trace
Implement Trace
Start an existing Trace as a developer.
Read the full spec (Trace + Feature + Epic). The Trace's contract is its Scenario Claim. Map the claim to the actual codebase. Propose a concrete technical approach. Drive implementation test-first against each claimed Gherkin scenario. Leave the system releasable on merge.
The expected Trace issue body structure is defined in @.github/ISSUE_TEMPLATE/TRACE.md.
Process
0. GitHub CLI setup
Run steps 1–2 of ../references/gh-setup.md (install check and auth check). If gh is not installed or not authenticated, stop. Extensions are not required for this skill.
If this skill was invoked from wtf.write-trace, wtf.loop, or another skill that already ran gh-setup this session, skip this step.
1. Identify the Trace
Call AskUserQuestion (per ../references/questioning-style.md):
- question: "Which Trace are you implementing?"
- header: "Trace"
- options: from recent open Trace issues (list per
../references/issue-classification.md)
Walk Trace → Feature → Epic per ../references/spec-hierarchy.md. Extract:
- Trace: Story, Scenario Claim, synced scenario copy, Spine Position (with Builds-on Traces), Contracts & Interfaces, DoD.
- Feature: ACs, User Stories with canonical Gherkin scenarios, Trace Plan, delivery override (when present).
- Epic: Goal and constraints.
2. Resolve the claimed scenarios
The Feature body is canonical for scenario text. The Trace body carries a synced courtesy copy. Take each scenario name from the Scenario Claim. Find its canonical text in the Feature body.
If the Trace's synced copy differs from the Feature's canonical text, the Feature wins. Tell the user about the drift. Recommend wtf.refine on the Feature to re-sync the copy. Continue with the canonical text.
If a claimed scenario name does not exist in the Feature body, stop and ask the user. Do not invent scenario text.
The resolved canonical scenarios drive the TDD cycle in step 8. Only the claimed scenarios are in scope — never the story's full scenario list.
3. Lifecycle check
Apply the absent-label gate from ../references/lifecycle-labels.md for the designed label on the Trace.
Recommended skill: wtf.design-trace. Header: Design check.
On Design it first → follow wtf.design-trace and pass the Trace number as context. On Skip design → continue. If the label is present, continue silently.
4. Load the technical steering document
Load docs/steering/TECH.md per the strict consumer-side load in ../references/steering-doc-process.md (recommended skill: wtf.steer-tech). Apply its stack, architecture patterns, key constraints, commands, and ADRs silently throughout this session.
5. Sequencing gate and branch setup
A Trace needs the code of the Trace it builds on, not its merge. Each Feature delivers through one linear stack of Trace PRs, and this Trace branches off its top. Before you branch:
-
Readiness. Read the Builds-on Trace numbers from the Spine Position section. Each one must have joined the stack (its PR is open) or merged. Check each one:
gh pr list --state all --limit 500 --json number,state,headRefName \ --jq '.[] | select(.headRefName | startswith("trace/<n>-")) | "\(.number) \(.state)"'OPEN→ it joined the stack. Do not wait for its merge.MERGED→ its code is on the feature branch (staged) ormain(trunk).- Only a branch, no PR → it has not joined. Nothing stacks on a branch without a PR. Tell the user to open its PR first with
wtf.create-pr, then stop. - Neither → the Trace this one builds on has not been implemented. Warn the user and stop. Continue only when the user explicitly overrides.
A Skeleton builds on nothing. It passes this gate without a check.
-
Stack base. Run the Resolve the stack base procedure in
../references/branch-setup.md. It walks the open Trace PRs of the Feature from the root to the tip. The tip is the stack base. With no open Trace PR, the base is the feature branch (staged) ormain(trunk). -
Green check. When the stack base is a
trace/*branch, verify it is green: rungh pr checks <pr_number>on its PR. If there is no CI, run the project's test command on that branch once. If the branch is red, warn the user and ask before stacking on it.
A sibling can join the stack while this Trace builds. That is expected. wtf.create-pr rebases onto the new tip before the PR opens (see "Join the stack" in ../references/branch-setup.md).
Then set up branches per ../references/branch-setup.md: resolve the delivery mode (config plus per-feature override), generate the slug, and create or resume trace/<trace-number>-<trace-slug> off the stack base. In staged delivery, create or check out the feature branch first when the stack base is the feature branch. In trunk delivery, do not create a feature branch. Resolve any conflicts before you continue.
Tell the user what this Trace stacked on. Its PR targets the stack tip at the time the PR opens.
6. Explore the codebase
Before you explore, identify the test framework setup. Read a sample of existing test files. Record the following in a working scratchpad before you continue. These govern every test written in step 8:
| Field | Value |
|---|---|
| Test framework | (e.g. Jest, Vitest, pytest, RSpec) |
| Test file pattern | (e.g. **/*.test.ts, tests/test_*.py) |
| Import convention | (e.g. import { describe, it } from 'vitest') |
| Run command | (e.g. npm test, pytest) |
| Coverage command | (e.g. npm run coverage, pytest --cov) |
Use the Agent tool to find, with independent searches in parallel:
- The files and modules this Trace will touch — search for the domain nouns and verbs from the story and the claimed scenarios
- The current definition of every interface or type named in the Contracts section
- Existing tests that cover adjacent behavior, near the integration points found above
- The domain objects and services this Trace depends on, and where they are imported — these must exist first
Extension or Deepening Traces: also read the PRs and commits of the Traces this one builds on (gh pr view, git log --oneline <base-branch>). The earlier Traces laid the Spine. Find the seams they created — the modules, interfaces, and test files this Trace extends. Build on those seams. Do not create parallel structures.
Also fetch any relevant wiki pages or in-repo glossary docs for this Trace's Bounded Context. Use these so the implementation and test naming align with the team's Ubiquitous Language.
7. Draft the Technical Approach
Apply strict STE per ../references/ste-writing.md before you write any durable body (Technical Approach prose and later issue updates). Commit subject/body prose follows STE via ../references/commit-conventions.md.
Skeleton directive. When the Trace's Spine Position is Skeleton, hold this line through the approach and the whole implementation:
Build the MINIMAL end-to-end path through every layer for the claimed happy-path scenario. Touch each layer once — data, logic, interface — with the least code that makes the scenario pass at production quality. Do not gold-plate. Do not add speculative endpoints, configuration, options, or abstractions for scenarios not in the claim. Do not generalize for imagined future needs. Production quality is required — error handling and tests for the claimed path — but feature-complete is not. The Deepening Traces add the rest.
When the Position is Extension or Deepening: build on the Spine the earlier Traces laid (seams found in step 6). Extend their modules and interfaces. Keep the approach scoped to the claimed scenarios.
Produce a concrete Technical Approach with actual file paths (not generic layer names):
- Architecture decisions: which layer owns what, which patterns to follow, which existing seams this Trace extends
- Data flow: how data moves from input to output, with the concrete file paths touched
- Trade-offs: what alternatives were considered and why this approach was chosen
- Aggregates & Invariants: which Aggregates this Trace modifies, and which business rules must hold after the change
8. Review approach with user
Show the Technical Approach. Then call AskUserQuestion (per ../references/questioning-style.md):
- question: "Does this align with how you'd approach it?"
- header: "Approach review"
- options:
- Yes — looks good, proceed → continue with implementation
- I have constraints to share → adjust the approach first
- Suggest an alternative → describe a different approach
Apply changes. Then update the Trace issue's Technical Approach section (including Aggregates & Invariants). Also fill or refine ## Impacted Areas with the concrete paths the approach names — the conflict graph schedules sibling Traces by this section, and an empty section serializes this Trace against every sibling.
See
references/issue-body-update-pattern.mdfor the read-merge-write pattern (it goes through the gh body helper).
python3 .wtf/gh-body.py read <trace_number> # prints a temp path; Read it, merge in the Technical Approach
python3 .wtf/gh-body.py edit <trace_number> --body-file "<path-from-read>"
9. Drive the TDD cycle
Process the claimed scenarios (resolved in step 2) in order — only those, never the story's unclaimed scenarios. Match the project's established test patterns discovered in step 6. Reference the Contracts & Interfaces section for exact request/response shapes.
-
Write the failing test for the scenario.
-
Implement the minimum code to make it pass.
-
Refactor if needed. Keep functions under 40 lines. Avoid deep nesting.
-
Commit — atomic semantic commit per
../references/commit-conventions.md. Use theScenario:andTrace:trailers:git add <changed files> git commit -m "<type>(<scope>): <short description> Scenario: <scenario name> Trace: #<trace_number>" -
Do not skip ahead. Each scenario is a checkpoint.
Once all claimed scenarios are green, run the full lint and type-check gate once across all changes. Check package.json for lint, typecheck, type-check, or check script keys. Run whichever exist:
# e.g. npm run lint && npm run typecheck
Fix any issues before you continue to coverage.
10. Verify coverage and releasability
Once all claimed scenarios pass, confirm unit test coverage meets the minimum threshold for all new and modified code.
Use the threshold specified in docs/steering/QA.md if it exists. Default to 80% if the document is absent or does not define a threshold:
# Run the project's coverage command (check package.json scripts)
If coverage is below 80% on any new or modified file, add targeted tests before you continue. Every public function must have at least one happy-path and one error-path test.
Releasability check. Every Trace leaves the system releasable after merge — the DoD says so, and a Skeleton is never a prototype. Run the full existing test suite, not only the new tests. If any previously green test broke, fix it before you continue. Unfinished paths outside the claim must fail safely, not half-work.
11. Update Test Mapping
Fill the Test Mapping table in the Trace issue with concrete file paths:
| Claimed scenario | Test file | Status |
|---|---|---|
<scenario name> | <test file path:line> | passing |
See
references/issue-body-update-pattern.mdfor the read-merge-write pattern. Re-readthe body (do not reuse the temp file from step 8).
python3 .wtf/gh-body.py read <trace_number> # re-fetch; prints a fresh temp path; Read it, update the Test Mapping table
python3 .wtf/gh-body.py edit <trace_number> --body-file "<path-from-read>"
Print the updated Trace issue URL.
12. Mark implemented, report learnings, offer to continue
Add the implemented lifecycle label. This is mandatory regardless of invocation mode:
gh issue edit <trace_number> --add-label "implemented"
Learnings capture. End the completion output with one short structured block that states what this Trace revealed — surprises in the codebase, drift between spec and reality, discovered edge cases, scenarios that look wrong or missing. wtf.loop feeds this block to headless wtf.refine as the re-aim insight:
Revealed:
- <surprise, drift, or discovered edge case>
- <...>
If the Trace revealed nothing, state Revealed: nothing — plan held. Do not omit the block.
If invoked from the loop (non-interactive mode), skip the ask below and return control to the loop.
Call AskUserQuestion (per ../references/questioning-style.md):
- question: "What's next?"
- header: "Next step"
- options:
- Verify this Trace → follow
wtf.verify-trace, passing the Trace number in as context (recommended) - Open a pull request → follow
wtf.create-pr, passing the Trace number and branch in as context - Implement another Trace → restart this skill from step 1
- Verify this Trace → follow
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |