implement

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- sage-metadata
cost-tier: sonnet
activation: auto
tags: [implementation, coding, development]
inputs: [task-spec, plan, codebase-context, constitution]
outputs: [implementation, test-suite]
requires: [tdd, scope-guard]
-->

# Implement

Write code for one task. Follow TDD. Stay in scope. Commit.

**Core Principle:** Implementation is the mechanical part. The thinking was done
in the spec and plan. Your job now is to faithfully translate the plan into working,
tested code — not to redesign, optimize, or "improve" beyond what was specified.

## When to Use

During the execution phase of any workflow, when a task from the plan is ready
for implementation.

## Process

### Step 1: Read the Task Completely

Read the full task specification from the plan. Understand:
- What files to create or modify
- What the code should do
- What test to write
- How to verify completion
- What this task depends on (verify dependencies are complete)

If anything is unclear, ASK before proceeding. Guessing at requirements
causes rework. It is always faster to ask one question than to rewrite
200 lines of code.

### Step 2: Check Conventions

Reference the codebase-scan output and `.sage/conventions.md`:
- What patterns are used for similar code in this project?
- What naming conventions apply?
- What test patterns are established?
- What import style is used?

Your implementation MUST follow existing conventions unless the task
explicitly requires deviating from them.

### Step 3: Implement Using TDD

Follow the `tdd` skill strictly:

1. **Write the test first.** The test describes the behavior from the task spec.
   Watch it fail. Verify it fails for the right reason.
2. **Write minimal code to pass.** Only enough to make the test green.
   Don't add error handling, edge cases, or optimizations not required by the task.
3. **Refactor if needed.** Clean up duplication. Improve names. Keep tests green.
4. **Repeat** for each behavior in the task.

### Step 4: Self-Review Before Committing

Before declaring the task complete, check:

- [ ] Every piece of the task spec is implemented
- [ ] Every behavior has a test that was written FIRST
- [ ] All tests pass (run them, don't assume)
- [ ] No code outside the task scope was changed (scope-guard)
- [ ] Code follows project conventions (from codebase-scan)
- [ ] No TODO/FIXME/HACK comments added (fix it now or don't do it)

### Step 5: Update Plan Progress

**This is the critical persistence step.** After committing, update the plan file
to record completion. This is NOT optional — it IS the state persistence mechanism.

In the plan file (`.sage/work/<feature>/plan.md`):
1. Check the task's checkbox: `- [ ]` → `- [x]`
2. Add the completion marker after the task name: `✅ DONE (commit: <hash>)`
3. Fill in the gate results in the Gate Log table (after gates run)
4. Update the plan's `**Last updated:**` timestamp
5. If this was the last task, update `**Status:**` to `complete`

**Why this matters:** If the session ends unexpectedly — terminal closed, context
window full, connection dropped — the plan file on disk shows exactly which tasks
are done. The next session reads the plan file, sees the checkboxes, and resumes
from the right place. This works because artifacts are the source of truth.

### Step 6: Commit

Write a semantic commit message:
```
<type>(<scope>): <short description>

<what was done and why, referencing the task>
```

Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`

## Rules

**MUST (violation = broken code or lost work):**
- MUST NOT implement multiple tasks without committing between them.
  Each task = one commit (or a small sequence of commits).
- MUST NOT skip TDD. The `tdd` skill is mandatory and has no exceptions.
- MUST NOT expand scope. The `scope-guard` skill is active. Do what the task says.
- MUST NOT guess at unclear requirements. Ask the human.
- MUST update plan checkboxes in bulk at the completion checkpoint (Rule 7).

**SHOULD (violation = suboptimal but working):**
- SHOULD follow existing project conventions over personal preference.
- SHOULD report if a task is harder than expected. Don't silently
  spend 30 minutes on a "5-minute task" without communicating.
- SHOULD use semantic commit messages following the type(scope): description format.

**MAY (context-dependent):**
- MAY split a commit into multiple smaller commits if the task has natural breakpoints.
- MAY ask the human to clarify conventions when existing code is inconsistent.

## Subagent Mode

From xoai/sage, MIT.

More from xoai/sage