Implement

Implement Mode

Recommended model tier: smart (opus) - this skill requires complex reasoning

Focused TDD implementation: make failing tests pass with minimal code.

Purpose

This is the DEV stage of the SDLC pipeline. Tests already exist from the TEST stage. Your job is to write the minimal implementation that makes them pass.

Prerequisites

Before starting:

• Tests exist and are failing (from TEST stage)
• Design/spec is available (from DESIGN stage)
• You know which files to create/modify

Workflow

Step 1: Verify Tests Exist and Fail

# Run the tests - they MUST fail initially
npm test -- path/to/feature.test.ts
# or
go test ./pkg/feature/...

If tests pass: The work is already done. Mark complete and move on.

If tests don't exist: This is wrong - go back to TEST stage.

Step 2: Read the Tests

Understand what the tests expect:

• What functions/methods need to exist?
• What are the expected inputs and outputs?
• What edge cases are covered?

# For large test files, get the structure first
mcp__plugin_aide_aide__code_outline file="path/to/feature.test.ts"

# Then read specific test sections with offset/limit
Read path/to/feature.test.ts offset=<start> limit=<count>

# For small test files (<100 lines), reading the full file is fine
Read path/to/feature.test.ts

When implementing, use code_outline on adjacent/related source files to understand their structure before reading them fully. This preserves context for the implementation work.

Step 3: Check Design Decisions

Use mcp__plugin_aide_aide__decision_get with the feature topic to review decisions from DESIGN stage. Use mcp__plugin_aide_aide__decision_list to see all project decisions.

Step 4: Implement Incrementally

Write code to make tests pass one at a time:

1. Pick the simplest failing test
2. Write minimal code to pass it
3. Run tests
4. If passing, move to next test
5. If failing, fix before proceeding

# Run specific test
npm test -- --grep "should create user"
# or
go test -run TestCreateUser ./pkg/...

Step 5: Backpressure Checkpoint (REQUIRED)

You CANNOT proceed until ALL tests pass.

# Full test run
npm test -- path/to/feature.test.ts
# or
go test -v ./pkg/feature/...

BLOCKING RULE: If any test fails:

1. Analyze the failure
2. Fix the issue
3. Re-run tests
4. Repeat until ALL pass

DO NOT skip failing tests. DO NOT proceed with red tests.

Step 6: Verify Build

# Ensure it compiles
npm run build
# or
go build ./...

Step 7: Commit

git add -A
git commit -m "feat: implement <feature> - tests passing"

Rules

1. Tests First: Never write code without a failing test
2. Minimal Code: Only write what's needed to pass tests
3. No Gold Plating: Don't add features not covered by tests
4. Red → Green: Tests must fail before they pass
5. Atomic Commits: One logical change per commit
6. No Skipping: Every test must pass

Common Patterns

TypeScript/JavaScript

// Read test expectations
describe("UserService", () => {
  it("should create user with email and name", async () => {
    const user = await service.createUser({
      email: "test@example.com",
      name: "Test",
    });
    expect(user.id).toBeDefined();
    expect(user.email).toBe("test@example.com");
  });
});

// Implement to match
export class UserService {
  async createUser(input: CreateUserInput): Promise<User> {
    return {
      id: crypto.randomUUID(),
      email: input.email,
      name: input.name,
      createdAt: new Date(),
    };
  }
}

Go

// Read test expectations
func TestCreateUser(t *testing.T) {
    svc := NewUserService()
    user, err := svc.CreateUser(context.Background(), CreateUserInput{
        Email: "test@example.com",
        Name:  "Test",
    })
    require.NoError(t, err)
    assert.NotEmpty(t, user.ID)
    assert.Equal(t, "test@example.com", user.Email)
}

// Implement to match
func (s *UserService) CreateUser(ctx context.Context, input CreateUserInput) (*User, error) {
    return &User{
        ID:        uuid.New().String(),
        Email:     input.Email,
        Name:      input.Name,
        CreatedAt: time.Now(),
    }, nil
}

Failure Handling

Test Won't Pass After Multiple Attempts

1. Re-read the test - is the expectation correct?
2. Check if test has a bug (it happens)
3. Check design decisions - is implementation matching spec?
4. Record blocker:

   ./.aide/bin/aide memory add --category=blocker --tags=project:<name>,session:<id>,source:discovered "Cannot pass test X: <reason>"
   

5. If you abandon the approach, record it so future sessions don't repeat it:

   ./.aide/bin/aide memory add --category=abandoned \
     --tags=reason:<why>,approach:<what>,project:<name>,session:<id>,source:discovered \
     "ABANDONED: <what was tried>. REASON: <why>. ALTERNATIVE: <new direction>. CONTEXT: <details>"
   

6. If stuck after 3 attempts, ask for help

Build Fails

1. Read error message carefully
2. Check for missing imports
3. Check for type mismatches
4. Fix and re-run build
5. Then re-run tests

Test Passes But Implementation Feels Wrong

1. If tests pass, the contract is met
2. Don't refactor during implement stage
3. Note concerns for future:

   ./.aide/bin/aide memory add --category=issue --tags=project:<name>,session:<id>,source:discovered "Implementation of X could be improved: <how>"
   

4. Proceed - refactoring is a separate concern

Binary location: The aide binary is at .aide/bin/aide. If it's on your $PATH, you can use aide directly.

Verification Checklist

Before completing:

• All tests pass (not just some)
• Build succeeds
• Changes are committed
• No debug code left (console.log, fmt.Println for debugging)

Completion

When all tests pass:

# Final verification
npm test -- path/to/feature.test.ts && npm run build

# Or Go
go test -v ./pkg/feature/... && go build ./...

Output: "Implementation complete. All tests passing. Ready for VERIFY stage."

Memory Hygiene

When storing memories from this skill (blockers, issues, abandoned approaches), always:

1. Include source: tag — Use source:discovered for things you found, source:inferred for deductions
2. Include scope tags — Add project:<name>,session:<id> (get project name from git remote or directory; session ID from $AIDE_SESSION_ID or $CLAUDE_SESSION_ID)
3. Verify codebase claims before storing — If a memory references a file, function, or path, confirm it exists first. See the memorise skill for the full verification workflow.
4. Never use scope:global unless storing a user preference

Integration with SDLC Pipeline

This skill is designed for the DEV stage:

[DESIGN] → [TEST] → [DEV/IMPLEMENT] → [VERIFY] → [DOCS]
                         ↑
                    YOU ARE HERE

• Input: Failing tests from TEST stage
• Output: Passing tests, working implementation
• Next: VERIFY stage runs full validation

Converted and distributed by TomeVault — claim your Tome and manage your conversions.