plan-editing-conventions

name	plan-editing-conventions
description	Conventions for editing plan.json implementation plans including task format, structured arrays, and plan structure rules. Use when creating or modifying plan.json files.

Plan Editing Conventions

Conventions for creating and modifying implementation plans stored as plan.json.

Plan Structure Rules

• Keep prose concise and actionable; include concrete file paths (relative/path.ts)
• Never include time estimates. Use qualitative Complexity per task: S (≤ ~120 LOC), M (~120–300 LOC), L (> ~300 LOC)
• Do not hardcode colors or tokens; reference semantic tokens when citing UI work

plan.json Format

The plan is stored as plan.json with these key fields:

{
  "content": "# Implementation Plan\n\n## Stage 1: ...\n\n### T-1.1: Task Title\n...",
  "acceptanceCriteria": [...],
  "pendingTasks": [...],
  "completedTasks": [...],
  "manualTasks": [...],
  "openQuestions": [...],
  "answeredQuestions": [...],
  "gaps": [...],
  "amendments": [...]
}

• content: The full markdown plan as a JSON string with escaped newlines (\n). This is the human-readable plan text.
• Structured arrays: Mirror the plan content for programmatic access (pendingTasks, completedTasks, etc.)

Editing plan.json Content Field

CRITICAL: The content field is a JSON string. When editing:

• Use \n escape sequences for newlines, NOT literal line breaks
• Ensure proper JSON escaping of quotes and special characters
• After editing, always sync plan.md via the code:extract-plan-md skill

Task Format

Tasks use the T-X.Y ID convention where X is the stage number and Y is the task number within that stage.

Each task in the plan content should follow this structure:

### T-X.Y: [Task Title]

**Files:** `path/to/file.ext`
**Complexity:** S | M | L
**AC Refs:** AC-001, AC-002

**Description:** Brief description of what this task accomplishes.

**Implementation Details:**

[Include one or more of the following as appropriate:]

**Mapping Table:** (for distribution/transformation tasks)
| Source | Target | Notes |
|--------|--------|-------|
| category_a | target_file_a.md | Section: XYZ |
| category_b | target_file_b.md | Section: ABC |

**Algorithm:** (for logic-heavy tasks)
1. Load input from `source_path`
2. Parse using `specific_method()`
3. For each item:
   a. Transform using pattern X
   b. Validate against schema Y
4. Write output to `target_path`

**Code Template:** (for new file creation)
```python
# Actual code structure to be created
from typing import TypedDict

class ConfigType(TypedDict):
    field_a: str
    field_b: int

def main_function(config: ConfigType) -> Result:
    """Docstring explaining purpose."""
    pass

Before/After Example: (for modification tasks)

# BEFORE (current code)
def old_approach():
    pass

# AFTER (with changes)
def new_approach():
    # Added: explanation of change
    pass

## Structured Array Format

### pendingTasks / completedTasks

```json
{
  "id": "T-1.1",
  "description": "Task description",
  "acceptanceCriteria": ["AC-001", "AC-002"]
}

amendments

{
  "timestamp": "2024-01-01T00:00:00",
  "changes": ["Description of change 1", "Description of change 2"],
  "conversation": [...]
}

Implementation Details Guidance

Extract implementation details for tasks that involve:

• Pattern extraction from existing code (algorithms, templates, mappings)
• Creating new files based on existing patterns
• Distributing/transforming content across multiple targets
• Complex logic that benefits from step-by-step documentation

Detail extraction checklist:

• Every task with Complexity M or L has implementation details
• Tasks referencing source files include extracted content
• Mapping/distribution tasks have explicit tables
• Algorithm tasks have step-by-step logic
• New file tasks have templates showing structure
• Code snippets use correct syntax highlighting

Skip detail extraction for:

• Simple file moves or renames (Complexity S, obvious path)
• Documentation-only tasks with no code
• Tasks that are pure analysis with no deliverable

Editing Existing Plans

When amending an existing plan:

1. Edit plan.json - Update the content field and structured arrays as needed
2. Keep arrays in sync - If a task moves from pending to completed, update both pendingTasks and completedTasks arrays
3. Preserve existing structure - Don't reorganize unless necessary
4. Update affected sections only - Minimize changes to unaffected tasks
5. Keep complexity accurate - Reassess if scope changes significantly
6. Sync plan.md - Always regenerate plan.md via code:extract-plan-md after edits