Cook

Language Adaptation

Detect the user's language from their first message. If the user writes in a non-English language, ALL skill output — status updates, slice reports, questions — MUST be in that language. Do not mix languages.

Language-Specific Conventions

Before writing any code, detect the project language and load the corresponding convention file:

Convention check hook: After touching ANY source file, verify the change against the loaded conventions BEFORE moving to the next step. If a violation is found, fix it immediately — do not proceed with a violation in place.

This is not optional. Every file touch triggers a convention check. No exceptions.

Overview

Build in thin vertical slices — implement one piece, test it, verify it, then move on. Never implement an entire feature in one pass. Each increment leaves the system in a working, testable state.

HARD GATE: Do NOT implement more than one slice without stopping to test and verify. Do NOT batch multiple slices into one pass. One slice at a time, no exceptions.

Modes

When to Use

• Plan is approved and it's time to code
• Implementing any multi-file change
• Building a new feature from a task breakdown
• Fixing bugs (use --tdd with the Prove-It Pattern)

When NOT to use: Single-line fixes, typo corrections, config-only changes.

The Increment Cycle (Default Mode)

┌──────────────────────────────────────┐
│                                      │
│   Implement ──→ Test ──→ Verify ──┐  │
│       ▲                           │  │
│       └───── Commit ◄─────────────┘  │
│              │                       │
│              ▼                       │
│          Next slice                  │
│                                      │
└──────────────────────────────────────┘

For each slice:

1. Implement the smallest complete piece of functionality
2. Test — run the test suite (or write a test if none exists)
3. Verify — confirm the slice works (tests pass, build succeeds)
4. Commit — save progress with a descriptive message
5. Report — tell the user what was done, what's next
6. STOP — wait for user confirmation before next slice

The TDD Cycle (--tdd Mode)

    RED                GREEN              REFACTOR
 Write a test    Write minimal code    Clean up the
 that fails  ──→  to make it pass  ──→  implementation  ──→  (repeat)
      │                  │                    │
      ▼                  ▼                    ▼
   Test FAILS        Test PASSES         Tests still PASS

Step 1: RED — Write a Failing Test

Write the test first. It MUST fail. A test that passes immediately proves nothing.

// RED: This test fails because createTask doesn't exist yet
@Test
void shouldCreateTaskWithDefaultStatus() {
	Task task = taskService.createTask("Buy groceries");

	assertThat(task.getId()).isNotNull();
	assertThat(task.getTitle()).isEqualTo("Buy groceries");
	assertThat(task.getStatus()).isEqualTo(TaskStatus.PENDING);
}

Step 2: GREEN — Make It Pass

Write the MINIMUM code to make the test pass. No over-engineering.

Step 3: REFACTOR — Clean Up

With tests green, improve the code without changing behavior. Run tests after every refactor step.

Then STOP. Report to user. Wait for confirmation before next cycle.

The Prove-It Pattern (Bug Fixes with --tdd)

Bug report arrives
       │
       ▼
  Write a test that demonstrates the bug
       │
       ▼
  Test FAILS (confirming the bug exists)
       │
       ▼
  Implement the fix
       │
       ▼
  Test PASSES (proving the fix works)
       │
       ▼
  Run full test suite (no regressions)

Slicing Strategies

Vertical Slices (Preferred)

Build one complete path through the stack:

Slice 1: Create a task (DB + API + basic UI)
    → Tests pass, user can create a task

Slice 2: List tasks (query + API + UI)
    → Tests pass, user can see their tasks

Slice 3: Edit a task (update + API + UI)
    → Tests pass, user can modify tasks

Each slice delivers working end-to-end functionality.

Risk-First Slicing

Tackle the riskiest piece first:

Slice 1: Prove the WebSocket connection works (highest risk)
Slice 2: Build real-time updates on the proven connection
Slice 3: Add offline support and reconnection

If Slice 1 fails, you discover it before investing in Slices 2 and 3.

Rules

Rule 1: One Thing at a Time

Each increment changes one logical thing. Don't mix concerns.

Bad: One commit that adds a new component, refactors an existing one, and updates the build config.

Good: Three separate increments.

Rule 2: Keep It Compilable

After each increment, the project MUST build and existing tests MUST pass.

Rule 3: Scope Discipline

Touch only what the task requires.

Do NOT:

• "Clean up" code adjacent to your change
• Refactor imports in files you're not modifying
• Add features not in the spec
• Modernize syntax in files you're only reading

Rule 4: Simplicity First

Before writing any code, ask: "What is the simplest thing that could work?"

SIMPLICITY CHECK:
✗ Generic EventBus with middleware pipeline for one notification
✓ Simple function call

✗ Abstract factory pattern for two similar components
✓ Two straightforward components with shared utilities

Rule 5: No Batch Implementation

NEVER implement multiple slices in one go. After each slice:

• Report what was done
• Show test results
• Wait for user to say "next" or redirect

This is non-negotiable. The user must see each slice land before the next begins.

Writing Good Tests (--tdd)

Test State, Not Interactions

Assert on the outcome, not on which methods were called internally.

Prefer Real Implementations Over Mocks

Preference order:
1. Real implementation  → Highest confidence
2. Fake               → In-memory version of dependency
3. Stub               → Returns canned data
4. Mock (interaction) → Use sparingly, at boundaries only

Arrange-Act-Assert Pattern

@Test
void shouldMarkOverdueTasksWhenDeadlinePassed() {
	// Arrange
	Task task = createTask("Test", LocalDate.of(2025, 1, 1));

	// Act
	OverdueResult result = checkOverdue(task, LocalDate.of(2025, 1, 2));

	// Assert
	assertThat(result.isOverdue()).isTrue();
}

One Assertion Per Concept

Each test verifies one behavior. Multiple assertions are fine if they verify the same concept.

Common Rationalizations

Red Flags

• More than 100 lines written without running tests
• Multiple unrelated changes in a single increment
• Implementing the next slice without reporting the previous one
• Skipping the test/verify step to move faster
• Build or tests broken between increments
• Writing code before a failing test exists (in --tdd mode)
• Running the same test command twice without code changes in between

Verification

After each slice:

• [ ] The change does one thing completely
• [ ] All existing tests pass
• [ ] Build succeeds
• [ ] New functionality works as expected
• [ ] Change is committed
• [ ] User was informed before moving to next slice

After all slices complete:

• [ ] Full test suite passes
• [ ] Feature works end-to-end as specified
• [ ] No uncommitted changes remain