| name | writing-plans |
| description | Use when an approved spec exists and you need a bite-sized, file-level implementation plan before any code is written. Produces a plan ready for executing-plans or subagent dispatch. |
Writing Plans — amd-smi
Translate an approved spec into a concrete plan an engineer (or fresh subagent) with zero project context can execute task-by-task. DRY. YAGNI. TDD. Frequent commits.
Announce at start: "I'm using the writing-plans skill to create the implementation plan."
Save plans to: ${TMPDIR:-/tmp}/amdsmi-agent-plans/YYYY-MM-DD-<feature-name>.md (ephemeral, never committed to the workspace)
Required Inputs
- An approved spec at
${TMPDIR:-/tmp}/amdsmi-agent-specs/YYYY-MM-DD-<topic>-design.md
- Familiarity with the amd-smi project layout (see
project-layout rule)
If no spec exists, STOP and invoke the amdsmi-interrogate skill first.
Scope Check
If the spec covers multiple independent subsystems, it should have been split during interrogate. If it wasn't, push back: each plan must produce working, testable software on its own. Suggest splitting before writing the plan.
File Structure (Map First)
Before writing tasks, map every file that will be created or modified and what each is responsible for. This locks in decomposition decisions.
For amd-smi work, this map almost always includes:
| Layer | Typical Files |
|---|
| Public header | include/amd_smi/amdsmi.h |
| C++ impl | src/amd_smi/amd_smi.cc, rocm_smi/src/*.cc |
| Wrapper | py-interface/amdsmi_wrapper.py (auto-generated — task = run tools/update_wrapper.sh) |
| Python API | py-interface/amdsmi_interface.py |
| CLI | amdsmi_cli/amdsmi_commands.py, amdsmi_parser.py, amdsmi_helpers.py |
| Tests | tests/amd_smi_test/, tests/python_unittest/ |
| Docs | docs/, CHANGELOG.md |
| Build | CMakeLists.txt, RPM/, DEBIAN/ |
Tasks should follow the cascade order so each commit builds independently.
Plan Document Header
Every plan starts with:
# <Feature Name> Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL — use `executing-plans` (or the `amdsmi-development` agent's subagent dispatch) to implement task-by-task. Steps use checkbox (`- [ ]`) syntax.
**Goal:** <one sentence>
**Spec:** <link to spec file>
**Architecture:** <2-3 sentences>
**Cascade layers touched:** <list>
---
Task Structure
Each task is a self-contained unit producing a single commit. Steps within a task are 2–5 minute actions.
### Task N: <Component Name>
**Files:**
- Create: `exact/path/to/file.cc`
- Modify: `exact/path/to/existing.h:42-58`
- Test: `tests/amd_smi_test/test_file.cc`
- [ ] **Step 1: Write the failing test**
```cpp
TEST_F(AmdSmiTest, AmdsmiGetNewFeature) {
amdsmi_status_t status = amdsmi_get_gpu_new_feature(handle, &out);
EXPECT_EQ(status, AMDSMI_STATUS_SUCCESS);
}
```
- [ ] **Step 2: Run test — verify it fails**
```bash
cd build && make -j$(nproc) amdsmitst
./tests/amd_smi_test/amdsmitst --gtest_filter=AmdSmiTest.AmdsmiGetNewFeature
```
Expected: FAIL — symbol not defined.
- [ ] **Step 3: Implement** (show full code, no `// ...existing...`)
- [ ] **Step 4: Run test — verify it passes**
- [ ] **Step 5: Commit**
```bash
git add include/amd_smi/amdsmi.h src/amd_smi/amd_smi.cc tests/amd_smi_test/test_file.cc
git commit -s -m "feat(amdsmi): add amdsmi_get_gpu_new_feature"
```
No Placeholders
The following are plan failures. Never write them:
TBD, TODO, implement later, fill in details- "Add appropriate error handling" / "handle edge cases" without showing the code
- "Write tests for the above" without the actual test code
- "Similar to Task N" — repeat the code; engineers may read tasks out of order
- References to types, functions, or methods not defined in any earlier task
Every step that changes code must show the code.
Self-Review
After writing the complete plan, re-read it against the spec:
- Spec coverage — every requirement maps to a task. List gaps; add tasks.
- Placeholder scan — none of the patterns above present
- Type consistency — function/type/field names match across tasks (a method called
clear_layers() in Task 3 and clearAllLayers() in Task 7 is a bug)
- Cascade completeness — header → impl → wrapper regen → interface → CLI → tests → docs → changelog all addressed
- Commit boundaries — each commit compiles independently when possible
Fix inline. Move on.
Execution Handoff
After saving the plan, offer the user a choice:
Plan saved to ${TMPDIR:-/tmp}/amdsmi-agent-plans/<filename>.md. Two execution options:
- Subagent-driven (recommended for multi-task plans) — invoke the
amdsmi-development agent or planning agent, fresh subagent per task with review between tasks
- Inline execution — execute tasks in this session using the
executing-plans skill, batched with checkpoints
Which approach?
If the planning agent dispatched this skill, return the plan path and the recommended execution mode rather than offering interactively.
