Commit cd79d9
2026-02-18 08:07:09 Thai Pangsakulyanont: -/-| /dev/null .. pdd/SKILL.md | |
| @@ 0,0 1,51 @@ | |
| + | --- |
| + | name: pdd |
| + | 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.' |
| + | --- |
| + | |
| + | ## What is PDD? |
| + | |
| + | 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. |
| + | |
| + | A good increment: |
| + | - **Passes tests** — never leave failing tests as technical debt |
| + | - **Has working stubs** — throws an error indicating that the stub is still unimplemented; never silently swallow unimplemented behaviour |
| + | - **Documents context** — the `@todo` comment should give the next agent enough to start without reading all the history |
| + | |
| + | ## @todo Comment Format |
| + | |
| + | ```js |
| + | // @todo #1234 Short description of what to implement: |
| + | // - Bullet point of expected behaviour |
| + | // - Reference to related patterns (e.g., "See <file> for ...") |
| + | // - Dependency notes (e.g., "Needs <something> from #1235") |
| + | doSomething() { |
| + | throw new Error("doSomething not yet implemented") |
| + | } |
| + | ``` |
| + | |
| + | Key rules: |
| + | - `@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. |
| + | - No iteration or phase numbers — don't write `@todo Add create action in phase 2`; implementation order can change |
| + | - For subsequent lines after the `// @todo`, indent by one space, i.e. add 2 spaces after the line comment, e.g. `// -`. |
| + | - Always pair the comment with a stub so callers fail loudly |
| + | |
| + | ## When to Wrap Up With a Stub |
| + | |
| + | If you're spending too long on a sub-task: |
| + | |
| + | 1. Get tests to pass with a minimal implementation |
| + | 2. Write a `@todo` comment that explains: |
| + | - The context on what you are working on |
| + | - What you tried and why it didn't work so far |
| + | - What the next agent needs to know to continue the work without repeating your failed attempts |
| + | |
| + | ## Picking Up an Existing Puzzle |
| + | |
| + | When you find a `@todo` to implement: |
| + | |
| + | 1. Read the comment fully — it should have context, bullets, and file references |
| + | 2. Check the ticket numbers in issue tracker for acceptance criteria |
| + | 3. Study the referenced files/patterns before writing code |
| + | 4. Remove both the `@todo` comment when the implementation is complete |
| + | 5. Run the relevant tests to confirm nothing breaks |