Mode 2 — Advanced Reference

Deep-dive reference for the restructure workflow. Read SKILL.md first.

Automation

Generate from JSON plan

Use when the source can be represented as structured JSON (e.g. exported from a project management tool or generated by a prior analysis step).

sh scripts/generate-structure.sh --plan plan.json
sh scripts/generate-structure.sh --example   # prints the expected JSON format

Expected JSON format:

{
  "outputPath": "docs/refactoring/phases",
  "phases": [{
    "number": 1,
    "name": "bootstrap",
    "description": "...",
    "type": "activities",
    "items": [{
      "number": 1,
      "name": "setup-toolchain",
      "description": "...",
      "subItems": [{
        "number": 1,
        "name": "install-deps",
        "description": "...",
        "checklist": ["item 1"],
        "acceptanceCriteria": ["criterion 1"],
        "status": "pending",
        "dependencies": []
      }]
    }]
  }]
}

Validate existing structure

sh scripts/validate-structure.sh <phases-dir>

Checks performed:

• READMEs present at every non-leaf directory
• All directory names are descriptive (not numeric-only)
• Required sections present in every leaf file
• All relative README links resolve
• Hierarchy depth does not exceed 4 levels
• No numeric-only directory names

Exit 0 = valid. Exit 1 = one or more violations (details printed to stdout).

Error recovery

Phase with 50+ items

Three options in order of preference:

1. Split by milestone — create phase-1a-, phase-1b- prefixes at a natural midpoint in the work
2. Extract verticals — if the phase mixes multiple features, give each feature its own phase
3. Promote to phase — if a group of 10+ items is cohesive and parallelisable, elevate it to a peer phase

Anti-pattern: just adding more nesting. Deep hierarchies with 50 siblings are still unusable regardless of depth.

Conflicting naming conventions

When the source mixes step-X.Y and activity-X.Y:

1. Choose the dominant pattern (whichever has more items)
2. Normalise everything to that pattern
3. Alternatively, use steps/ for implementation phases and activities/ for analysis phases (phase-aware dual convention)
4. Document the choice in a README note

Partial split (abandoned mid-work)

Diagnose the current state before continuing:

ls docs/refactoring/phases/*.md                          # flat files still in root
find docs/refactoring/phases -type d \
  -exec test ! -f {}/README.md \; -print                # dirs missing READMEs
git diff HEAD~5 --name-only | grep phases/              # recovery via git

Rule: complete partial splits before starting new ones. Incomplete hierarchies confuse agents reading the plan.

Items referencing non-existent parents

1. Renumber children to match the actual parent they belong to
2. Create the missing parent if children are cohesive (3+ items)
3. Flatten if only 1–2 children — they do not need a parent directory

Handling legacy conventions

When source documents use legacy naming (e.g. Activity 1.2.3 — Do thing):

1. Extract the semantic meaning, not the literal text
2. Normalise to outcome-based kebab-case names
3. Document the mapping in the phase README for traceability
4. Keep original IDs (1.2.3) in the leaf file title field for cross-referencing