Implement Skill

Quick Ref: Execute single issue end-to-end. Output: code changes + commit + closed issue.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Execute a single issue from start to finish.

Requires: bd CLI (beads) for issue tracking. Falls back to plain descriptions if unavailable.

Execution Steps

Given /implement <issue-id-or-description>:

Step 0: Check Issue State (Resume Logic)

Before starting implementation, check if resuming:

1. •Check if issue is in_progress:

bd show <issue-id> --json 2>/dev/null | jq -r '.status'

1. •

   If status = in_progress AND assigned to you:

   • •Look for checkpoint in issue notes: bd show <id> --json | jq -r '.notes'
   • •Resume from last checkpoint step
   • •Announce: "Resuming issue from Step N"
2. •

   If status = in_progress AND assigned to another agent:

   • •Report: "Issue claimed by <agent> - use bd update <id> --assignee self --force to override"
   • •Do NOT proceed without explicit override
3. •

   Store checkpoints after each major step:

bd update <issue-id> --append-notes "CHECKPOINT: Step N completed at $(date -Iseconds)" 2>/dev/null

Step 1: Get Issue Details

If beads issue ID provided (e.g., gt-123):

bd show <issue-id> 2>/dev/null

If plain description provided: Use that as the task description.

If no argument: Check for ready work:

bd ready 2>/dev/null | head -3

Step 2: Claim the Issue

bd update <issue-id> --status in_progress 2>/dev/null

Step 3: Gather Context

USE THE TASK TOOL to explore relevant code:

Tool: Task
Parameters:
  subagent_type: "Explore"
  description: "Gather context for: <issue title>"
  prompt: |
    Find code relevant to: <issue description>

    1. Search for related files (Glob)
    2. Search for relevant keywords (Grep)
    3. Read key files to understand current implementation
    4. Identify where changes need to be made

    Return:
    - Files to modify (paths)
    - Current implementation summary
    - Suggested approach
    - Any risks or concerns

Step 4: Implement the Change

Based on the context gathered:

1. •Edit existing files using the Edit tool (preferred)
2. •Write new files only if necessary using the Write tool
3. •Follow existing patterns in the codebase
4. •Keep changes minimal - don't over-engineer

Step 5: Verify the Change

Success Criteria (all must pass):

• • All existing tests pass (no new failures introduced)
• • New code compiles/parses without errors
• • No new linter warnings (if linter available)
• • Change achieves the stated goal

Check for test files and run them:

# Find tests
ls *test* tests/ test/ __tests__/ 2>/dev/null | head -5

# Run tests (adapt to project type)
# Python: pytest
# Go: go test ./...
# Node: npm test
# Rust: cargo test

If tests exist: All tests must pass. Any failure = verification failed.

If no tests exist: Manual verification required:

• • Syntax check passes (file compiles/parses)
• • Imports resolve correctly
• • Can reproduce expected behavior manually
• • Edge cases identified during implementation are handled

If verification fails: Do NOT proceed to Step 5a. Fix the issue first.

Step 5a: Verification Gate (MANDATORY)

THE IRON LAW: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Before reporting success, you MUST:

1. •IDENTIFY - What command proves this claim works?
2. •RUN - Execute the FULL command (fresh, not cached output)
3. •READ - Check full output AND exit code
4. •VERIFY - Does output actually confirm the claim?
5. •ONLY THEN - Make the completion claim

Forbidden phrases without fresh verification evidence:

• •"should work", "probably fixed", "seems to be working"
• •"Great!", "Perfect!", "Done!" (without output proof)
• •"I just ran it" (must run it AGAIN, fresh)

Rationalization Table

Store checkpoint:

bd update <issue-id> --append-notes "CHECKPOINT: Step 5a verification passed at $(date -Iseconds)" 2>/dev/null

Step 6: Commit the Change

If the change is complete and verified:

git add <modified-files>
git commit -m "<descriptive message>

Implements: <issue-id>"

Step 7: Close the Issue

bd update <issue-id> --status closed 2>/dev/null

Step 8: Report to User

Tell the user:

1. •What was changed (files modified)
2. •How it was verified (with actual command output)
3. •Issue status (closed)
4. •Any follow-up needed

Output completion marker:

<promise>DONE</promise>

If blocked or incomplete:

<promise>BLOCKED</promise>
Reason: <why blocked>

<promise>PARTIAL</promise>
Remaining: <what's left>

Key Rules

• •Explore first - understand before changing
• •Edit, don't rewrite - prefer Edit tool over Write tool
• •Follow patterns - match existing code style
• •Verify changes - run tests or sanity checks
• •Commit with context - reference the issue ID
• •Close the issue - update status when done

Without Beads

If bd CLI not available:

1. •Skip the claim/close status updates
2. •Use the description as the task
3. •Still commit with descriptive message
4. •Report completion to user