Cook

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:

Project type	Convention source
Java (*.java, pom.xml, build.gradle)	/java-developer command

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

Flag	Behavior
(default)	Incremental implementation with tests after each slice
--tdd	Strict RED → GREEN → REFACTOR. Test written FIRST, must FAIL before any implementation

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

Rationalization	Reality
"I'll test it all at the end"	Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong.
"It's faster to do it all at once"	Feels faster until something breaks and you can't find which of 500 lines caused it.
"These changes are too small to commit separately"	Small commits are free. Large commits hide bugs.
"This is too simple to test"	Simple code gets complicated. The test documents expected behavior.
"I'll write tests after the code works"	You won't. And tests written after test implementation, not behavior.
"Let me just quickly add this too"	Scope expansion. Stop.

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