Use when asked to generate an implementation plan, draft a plan, save a plan, or design a feature rollout for the Argus 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.
Use when asked to generate an implementation plan, draft a plan, save a plan, or design a feature rollout for the Argus 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 Argus
Create well-structured implementation plans that follow Argus'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 release dashboard query time from 5s to under 500ms" 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:
