writing-plans - SKILL.md Agent Skill

name: writing-plans description: >- Use when asked to generate an implementation plan, draft a plan, save a plan, or design a feature rollout for the SCT repository. 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, stored in docs/plans/mini-plans/). Routes automatically based on PR plans label, user input, or task size estimate.

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.

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.

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 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:

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:

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 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 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 for the full catalog with before/after examples and the quick-reference table.

Reference Index

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

Workflow	Purpose
create-a-plan.md	5-phase process for writing a full implementation plan from scratch
create-a-mini-plan.md	3-phase lightweight workflow for writing a mini-plan
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
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)
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