Home Changelog
Page Index

An Otter Wiki

Blame

cd79d9 Thai Pangsakulyanont 2026-02-18 08:07:09 1 
---
2
name: pdd
3
description: 'Skills for Puzzle Driven Development (PDD). Refer to this skill when a project uses PDD or the operator mentions PDD or puzzle-driven development. Use this skill when: (1) Breaking a large feature into incremental deliverables, (2) Writing @todo stub comments to mark unimplemented code, (3) Picking up an existing @todo puzzle to implement, (4) Deciding whether to wrap up a task with a stub or keep working.'
4
---
5
6
## What is PDD?
7
8
Puzzle Driven Development breaks features into small, working increments. Each increment leaves `@todo` puzzle comments marking deferred work. This lets multiple agents (AI or human) work in parallel and progress without being blocked by incomplete pieces.
9
10
A good increment:
11
- **Passes tests** — never leave failing tests as technical debt
12
- **Has working stubs** — throws an error indicating that the stub is still unimplemented; never silently swallow unimplemented behaviour
13
- **Documents context** — the `@todo` comment should give the next agent enough to start without reading all the history
14
15
## @todo Comment Format
16
17
```js
18
// @todo #1234 Short description of what to implement:
19
// - Bullet point of expected behaviour
20
// - Reference to related patterns (e.g., "See <file> for ...")
21
// - Dependency notes (e.g., "Needs <something> from #1235")
da80b1 Thai Pangsakulyanont 2026-02-18 08:09:52 22
// - Acceptance criteria
cd79d9 Thai Pangsakulyanont 2026-02-18 08:07:09 23
doSomething() {
24
throw new Error("doSomething not yet implemented")
25
}
26
```
27
28
Key rules:
29
- `@todo` followed by the ticket you are working on. For example, if you are working on issue #1234 say `@todo #1234`. The ticket reference will depend on the issue tracking system used, e.g. `#1234` for GitHub, or `ABC-1234` for Jira/Linear, or `CLAUDE-1` for Claude Code's built-in task list. If it is unclear which ticket is being worked on, ask the operator for this information before continuing.
30
- No iteration or phase numbers — don't write `@todo Add create action in phase 2`; implementation order can change
31
- For subsequent lines after the `// @todo`, indent by one space, i.e. add 2 spaces after the line comment, e.g. `// -`.
32
- Always pair the comment with a stub so callers fail loudly
33
34
## When to Wrap Up With a Stub
35
da80b1 Thai Pangsakulyanont 2026-02-18 08:09:52 36
If you think you're spending too long on a task:
cd79d9 Thai Pangsakulyanont 2026-02-18 08:07:09 37
38
1. Get tests to pass with a minimal implementation
39
2. Write a `@todo` comment that explains:
40
- The context on what you are working on
41
- What you tried and why it didn't work so far
42
- What the next agent needs to know to continue the work without repeating your failed attempts
da80b1 Thai Pangsakulyanont 2026-02-18 08:09:52 43
3. Create a task in your task list referring to the todo comment you created.
cd79d9 Thai Pangsakulyanont 2026-02-18 08:07:09 44
45
## Picking Up an Existing Puzzle
46
47
When you find a `@todo` to implement:
48
49
1. Read the comment fully — it should have context, bullets, and file references
50
2. Check the ticket numbers in issue tracker for acceptance criteria
51
3. Study the referenced files/patterns before writing code
da80b1 Thai Pangsakulyanont 2026-02-18 08:09:52 52
4. Remove the `@todo` comment when the implementation is complete
cd79d9 Thai Pangsakulyanont 2026-02-18 08:07:09 53
5. Run the relevant tests to confirm nothing breaks