# Writing Plans

> Write, review, or restructure an implementation plan for the SCT repository. Triggers: "create a plan", "write a plan", "draft a plan", "save a plan", "make a plan for", "generate an implementation plan", "planning document", "design doc", "implementation roadmap", "feature rollout", "mini-plan", "break this into phases", "plan before implementing", or reviewing and shortening an existing plan. Supports two formats: full 7-section plans for multi-phase work (1K+ LOC, tracked in MASTER.md) and lightweight mini-plans for single-PR changes (under 1K LOC, in docs/plans/mini-plans/). Routes automatically based on PR plans label, user input, or task size estimate.

- Skill: `scylladb/writing-plans` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add scylladb/writing-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scylladb/writing-plans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning, Docs & Writing, Productivity
- Author: scylladb (https://skillmd.com/u/scylladb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/scylladb/writing-plans

---


# Writing Implementation Plans for SCT

Create well-structured implementation plans that follow SCT's 7-section format and enable incremental, PR-scoped development.

## Essential Principles

### Authoritative Source

**`docs/plans/INSTRUCTIONS.md` is the authoritative source for plan structure.**

This skill supplements — not replaces — the official instructions. Always read `docs/plans/INSTRUCTIONS.md` before writing a plan. If there is a conflict between this skill and `INSTRUCTIONS.md`, follow `INSTRUCTIONS.md`.

### Behaviour Over Code

**A plan describes intended behaviour and design goals — not the code that will implement them.**

Write what should happen and why; leave the "how" to the PR. No line numbers, no snippets of internal logic, no file-internal detail. Test: if a sentence would have to change because someone refactored a function *without changing its behaviour*, it does not belong in the plan. This is the most common review complaint on SCT plans — see [PAP-1, PAP-9, PAP-10, PAP-11](references/anti-patterns.md) for what to cut and how.

### One Plan, One Concern

**If part of the plan could ship as its own independent effort, split it into its own plan.**

A cluster of open questions in one area is the signal that the area is separable — and that it is blocking review of the part that is ready. See [PAP-12](references/anti-patterns.md).

### Code-Verified Current State

**The Current State section must reference real files, classes, and methods.**

Use file-reading tools to inspect actual code before writing Current State. Do not guess or hallucinate file names. Every path mentioned must resolve to an existing file in the repository. Reference by symbol (`file.py:ClassName`), never by line number — see "Behaviour Over Code" above.

### PR-Scoped Phases

**Each implementation phase should be scoped to a single Pull Request.**

Large phases that span multiple PRs are hard to review and test. Break work into atomic phases with clear Definition of Done criteria. Within a PR, split logically distinct changes into separate commits for easier review. Order phases by dependency — foundational refactoring before feature implementation.

### Measurable Goals

**Goals and success criteria must be measurable, not vague.**

"Improve performance" is not a goal. "Reduce health check time from 120 minutes to under 12 minutes for 60-node clusters" is a goal. Include numbers, thresholds, or verifiable conditions.

### Investigation Over Assumption

**Mark unclear requirements as "Needs Investigation" instead of assuming.**

When information is missing or ambiguous, explicitly flag it. Incorrect assumptions in a plan propagate through the entire implementation and cause rework.

### Every Plan Must Have Status Metadata

**All plans require YAML frontmatter with status, domain, and dates.**

Plans without metadata are invisible to the tracking system. Every plan file must start with frontmatter specifying `status`, `domain`, `created`, `last_updated`, and `owner` fields. This enables `MASTER.md` and `progress.json` to reflect accurate state. See [frontmatter-fields.md](references/frontmatter-fields.md) for valid values.

## Plan Type Routing

When the user asks to "save a plan", "draft a plan", or similar, determine the plan type **before writing anything**.

### Decision Tree

```
1. User explicitly said big/small?       -> Use that
2. Working on a PR with `plans` label?   -> FULL plan
3. Working on a PR without `plans` label? -> MINI-plan
4. No PR context?                        -> Ask user, or estimate: >=1K LOC -> FULL, <1K LOC -> MINI
```

### Step 1: Ask the User (Preferred)

When explicitly asked to create/save a plan, ask:

> "Is this a big plan (multi-phase, 1K+ LOC, needs tracking) or a small plan (single PR, under ~1K LOC)?"

The user's answer is authoritative. If they say "small" -> mini-plan. If they say "big" -> full plan.

**When user says "big":** If already working on a PR, add the `plans` label immediately:
```bash
gh pr edit <number> --add-label "plans"
```
If a PR hasn't been opened yet, include a reminder in the plan output: "Remember to add the `plans` label when the PR is created." The agent should also add the label automatically when it later creates the PR during that session.

### Step 2: PR Label Check (When Working on an Existing PR)

If the agent is already working on a PR (e.g., from `gh pr checkout`), check for the `plans` label:

```bash
gh pr view <number> --json labels --jq '.labels[].name' | grep -q '^plans$'
```

- PR has `plans` label -> FULL plan (7-section, `docs/plans/`)
- PR does NOT have `plans` label -> MINI-plan (4-section, `docs/plans/mini-plans/`)

### Step 3: Fallback Heuristic (Only if No User Answer and No PR Context)

Estimate the scope from the task description:

- **Likely big:** Multiple new files, new config parameters, multiple backends affected, needs CI changes
- **Likely small:** Single file change, bug fix, test addition, refactoring one module
- **When in doubt, ask the user** rather than guessing

## When to Use

- When asked to "generate an implementation plan", "draft a plan", or "save a plan"
- When designing a multi-phase feature rollout for SCT (-> full plan)
- When a complex change needs to be broken into PR-scoped steps (-> full plan)
- When documenting a refactoring strategy before implementation (-> full plan)
- When creating a roadmap for a new SCT capability (-> full plan)
- When reviewing or improving an existing plan
- When a small, single-PR change benefits from lightweight planning (-> mini-plan)
- When working on a PR without a `plans` label and want to document approach (-> mini-plan)

## When NOT to Use

- For trivial changes that need no planning at all — just implement directly
- For regular coding questions — answer them without plan structure
- For documentation-only changes — edit the relevant file directly
- For updating an existing plan's status — edit the plan file directly

## The 7-Section Structure

Every SCT plan follows this structure. See [plan-templates.md](references/plan-templates.md) for detailed templates and examples.

| # | Section | Purpose | Key Rule |
|---|---------|---------|----------|
| 1 | Problem Statement | What and why | Include measurable pain points |
| 2 | Current State | What exists today | MUST reference real files (verify with tools) |
| 3 | Goals | What success looks like | Numbered, measurable objectives |
| 4 | Implementation Phases | How to get there | PR-scoped (≤200 LOC), Importance levels, DoD per phase |
| 5 | Testing Requirements | How to verify | Unit, integration, and manual testing planned upfront |
| 6 | Success Criteria | How to know it's done | References DoD items; add plan-level criteria only if needed |
| 7 | Risk Mitigation | What could go wrong | Likelihood, impact, mitigation for each risk |

## Plan File Conventions

| Convention | Rule |
|-----------|------|
| Location | `docs/plans/` directory |
| Filename | kebab-case, descriptive (e.g., `health-check-optimization.md`) |
| Format | Markdown with `# Plan Title` as first line |
| Archiving | Move completed plans to `docs/plans/archive/` |

## SCT-Specific Considerations

When writing plans for SCT, consider these domain-specific areas:

| Area | What to Include |
|------|----------------|
| **Backends** | Which backends are affected? (AWS, GCE, Azure, Docker, K8S, Baremetal) |
| **Configuration** | New parameters in `sdcm/sct_config.py` with defaults in `defaults/test_default.yaml` |
| **Nemesis** | Impact on chaos operations in `sdcm/nemesis/` (package: `__init__.py`, `registry.py`, `monkey/`, `utils/`) |
| **Monitoring** | Changes to Prometheus metrics, Grafana dashboards, or Argus reporting |
| **CI/CD** | Jenkins pipeline changes in `jenkins-pipelines/` |
| **Provision labels** | Which provision test labels to add (`provision-aws`, `provision-gce`, etc.) |
| **MASTER.md** | Register the plan in `docs/plans/MASTER.md` under the correct domain |
| **progress.json** | Add an entry to `docs/plans/progress.json` with plan metadata |
| **Related Plans** | Check MASTER.md for existing plans in the same domain that may overlap |

## Mini-Plan Format

Mini-plans are a lightweight 4-section format for small changes. See [mini-plan-template.md](references/mini-plan-template.md) for the full template and example.

| Aspect | Full Plan | Mini-Plan |
|--------|-----------|-----------|
| Sections | 7 | 4 (Problem, Approach, Files, Verification) |
| Frontmatter | Required | None |
| MASTER.md | Required | None |
| progress.json | Required | None |
| Location | `docs/plans/<domain>/` | `docs/plans/mini-plans/` |
| Filename | `kebab-case-name.md` | `YYYY-MM-DD-kebab-case-name.md` |
| Lifecycle | Tracked until archived | Disposable after PR merge or 30 days |

## Anti-Pattern Quick Reference

See [anti-patterns.md](references/anti-patterns.md) for the full catalog with before/after examples and the quick-reference table.

## Reference Index

| File | Content |
|------|---------|
| [plan-templates.md](references/plan-templates.md) | Complete plan skeleton, section-by-section templates with SCT-specific examples |
| [anti-patterns.md](references/anti-patterns.md) | Common plan writing mistakes with before/after fixes |
| [frontmatter-fields.md](references/frontmatter-fields.md) | YAML frontmatter field definitions, valid values, and domain taxonomy |
| [mini-plan-template.md](references/mini-plan-template.md) | Mini-plan 4-section template with example and rules |

| Workflow | Purpose |
|----------|---------|
| [create-a-plan.md](workflows/create-a-plan.md) | 5-phase process for writing a full implementation plan from scratch |
| [create-a-mini-plan.md](workflows/create-a-mini-plan.md) | 3-phase lightweight workflow for writing a mini-plan |
| [update-plan-status.md](workflows/update-plan-status.md) | 3-phase workflow for updating plan status across frontmatter, MASTER.md, and progress.json |

## Supporting Documents

| Document | Role |
|----------|------|
| `docs/plans/INSTRUCTIONS.md` | Authoritative source for plan structure and guidelines |
| `docs/plans/infrastructure/health-check-optimization.md` | Reference example: performance optimization plan |
| `docs/plans/nemesis/nemesis-rework.md` | Reference example: large-scale refactoring plan |

## Success Criteria

### Full Plan

- [ ] Passes `uv run sct.py pre-commit` without formatting issues
- [ ] Follows the 7-section structure from `docs/plans/INSTRUCTIONS.md`
- [ ] Has a Problem Statement with measurable pain points
- [ ] Has a Current State section with verified file/class/method references
- [ ] Describes behaviour, not code: no line-number refs (`grep -nE ':[0-9]+'` clean), no snippets beyond interfaces/config/API contracts, lifecycle stated once, one concern per plan (≈400 lines)
- [ ] Has numbered, measurable goals
- [ ] Has PR-scoped implementation phases (≤200 LOC each) with Importance levels and Definition of Done
- [ ] Includes a documentation update phase or deliverable (docs, config regeneration, guides)
- [ ] Has testing requirements covering unit, integration, and manual testing
- [ ] Has success criteria that reference DoD items (no duplication)
- [ ] Has risk mitigation with likelihood, impact, and mitigation for each risk
- [ ] Marks unclear requirements as "Needs Investigation"
- [ ] Is saved in `docs/plans/` with a kebab-case filename
- [ ] Has valid YAML frontmatter (status, domain, created, last_updated, owner)
- [ ] Is registered in `docs/plans/MASTER.md` under the correct domain
- [ ] Has a corresponding entry in `docs/plans/progress.json`

### Mini-Plan

- [ ] Has exactly 4 sections: Problem, Approach, Files to Modify, Verification
- [ ] Has no YAML frontmatter
- [ ] All file paths in "Files to Modify" are code-verified (or marked as new)
- [ ] Describes behaviour, not code: no line numbers, no snippets of internal logic, lifecycle stated once, one concern per plan (≈150 lines)
- [ ] Verification checklist has concrete, runnable checks
- [ ] Includes `uv run sct.py pre-commit` in verification
- [ ] Is saved as `docs/plans/mini-plans/YYYY-MM-DD-kebab-case-name.md`
- [ ] Is NOT registered in MASTER.md or progress.json