Plan Management

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.