plan-management

name	plan-management
description	Maintain consistent structure and format for IMPLEMENTATION_PLAN.md and SCOPE.md documents. Use when creating, updating, or reviewing the implementation plan or scope documents to ensure phase naming, section headers, checklist formats, status symbols, and notation follow project conventions.

Overview

This skill guides agents (mat-orchestrator, mat-tech-writer) in maintaining consistency across the Rename My Files project's planning documents. It ensures that IMPLEMENTATION_PLAN.md and SCOPE.md follow established conventions for structure, nomenclature, and progressive disclosure.

Important: These documents are internal only—for developers and architects. They are not shared with end users. End-user documentation lives separately in docs/ and must never reference planning documents (SCOPE.md, IMPLEMENTATION_PLAN.md, ADRs, etc.).

Key Conventions

Phase Naming & Status

Format: Phase [N] - [Descriptive Title]

Status Indicator:

• ✅ Complete — All tasks finished; no blockers
• ⏳ Not Started — Backlog; no active work
• 🔄 In Progress — Currently being worked on (use sparingly in plan; defer running tasks to actual tracking)

Example:

## Phase 0 - Cross-Platform Azure Tooling Migration

**Status:** ✅ **Complete**

**Objective:** Replace Azure PowerShell module with Azure CLI for cross-platform compatibility.

Completed Tasks Checklist

Use markdown checkboxes with [x] for complete tasks. Include brief descriptive text or code location references after each item.

Example:

### Completed Tasks

- [x] Replace Azure PowerShell module with Azure CLI.
  - [x] Update `Deploy-RenameMyFiles.ps1` to use `az` CLI commands.
  - [x] Update `Remove-RenameMyFilesResources.ps1` to use `az` CLI commands.
- [x] Add `restore: true` to Bicep template.

Section Structure

Each phase should follow this hierarchy:

## Phase [N] - [Title]

**Status:** [✅ **Complete** | ⏳ **Not Started** | ...]

**Objective:** [One sentence describing the phase goal]

### Completed Tasks / Planned Tasks

[Checklist items with descriptions]

### Why [Rationale or Decision Context]

[Optional context about decisions made]

**Note:** [Optional edge cases or limitations]

In-Document Links

Create relative links to planning documents and code:

Within plan/ folder:

• \[SCOPE.md\]\(SCOPE.md\) or \[DECISIONS/ADR-0001.md\]\(DECISIONS/ADR-0001.md\)

From docs/ folder back to plan/:

• \[../plan/DECISIONS/ADR-0003.md\]\(../plan/DECISIONS/ADR-0003.md\)

From root README.md:

• \[plan/SCOPE.md\]\(plan/SCOPE.md\)

Notation & Reserved Symbols

• ✅ = Completed/Done
• ⏳ = Not started/Backlog
• 🔄 = In progress
• ⚠️ = Warning/Caution
• 💡 = Insight or note
• ❌ = Failed/Won't do

Avoid other emoji or ad-hoc symbols; stick to this set for consistency across runs.

Code Location References

When referencing implementation code, use format:

Code location:\[file.ps1\]\(../../scripts/file.ps1#L123-L145) lines 123–145.
Rationale: [Explanation of why this approach was chosen.]

When to Use This Skill

✅ Use this skill when:

• Creating or updating IMPLEMENTATION_PLAN.md or SCOPE.md
• Reviewing plan documents for consistency
• Adding new phases, completed tasks, or notes
• Clarifying phase status or phase naming
• Establishing naming conventions for new ADR documents

❌ Do not use this skill for:

• Writing ADR documents (use adr-writing skill instead)
• Day-to-day task tracking (that's in actual GitHub issues/Projects)
• User-facing documentation (that's in docs/)

Reference Template

See references/TEMPLATE.md for a full phase template you can copy and customize.