sync-planning

name	sync-planning
description	Update planning docs and create tickets based on discrepancies report. Use this skill after running analyze-gaps to create tickets for unbuilt features and update roadmap. Handles DOCUMENTED_NOT_IMPLEMENTED gaps.

Sync Planning

Updates planning documentation and creates tickets for unbuilt features based on the discrepancies report generated by analyze-gaps.

Prerequisites

• Run analyze-gaps skill first
• docs/1-prd/99-discrepancies.md must exist with Status: COMPLETE

When to Use

• After analyze-gaps identifies unbuilt features
• When PRD has features not yet implemented
• When planning docs need to reflect current state
• To generate tickets for missing functionality

Gap Types Handled

Gap Type	Action
DOCUMENTED_NOT_IMPLEMENTED	Create new ticket
DIVERGED	May need ticket to align implementation

NOT handled (use sync-prd instead):

• IMPLEMENTED_NOT_DOCUMENTED - needs PRD update
• OUTDATED - needs PRD update

References

• references/ticket-workflow.md - Complete ticket structure, numbering, and document formats

Workflow

Step 1: Read Discrepancies

Read docs/1-prd/99-discrepancies.md:

1. Verify Status: COMPLETE (abort if still ANALYZING)
2. Parse the discrepancies report
3. Filter for planning-related gaps:
   • DOCUMENTED_NOT_IMPLEMENTED → needs tickets
   • DIVERGED → may need tickets if implementation should change
4. Ignore IMPLEMENTED_NOT_DOCUMENTED and OUTDATED gaps

Step 2: Read Planning State

Read existing planning documents:

1. docs/2-current/00-overall-plan.md - current roadmap
2. docs/2-current/02-completed.md - completed features
3. docs/tickets/index.md - existing tickets
4. Existing ticket definitions

Determine:

• Which features already have tickets
• Last ticket number (to continue numbering from)
• Current project phase

Ticket Numbering:

• Find highest existing ticket number (e.g., T00015)
• New tickets continue from next number (T00016, T00017, ...)
• Never reuse or skip numbers

Step 3: Update Planning Docs

Update docs/2-current/ documents:

00-overall-plan.md:

• Add new tickets to roadmap
• Update phases if needed
• Mark completed items appropriately
• Analyze ticket dependencies and development order (see below)

02-completed.md:

• Add any features found complete during analysis

If no new tickets needed and no plan updates, report and exit.

Ticket Dependencies Analysis

After listing all tickets in 00-overall-plan.md, add a dependencies section:

## Ticket Dependencies

### Dependency Graph
| Ticket | Depends On | Can Start After |
|--------|------------|-----------------|
| T00001 | - | Immediate |
| T00002 | - | Immediate |
| T00003 | T00001 | T00001 complete |
| T00004 | T00001, T00002 | T00001+T00002 complete |

### Parallel Development
Tickets that can be developed simultaneously:
- **Group 1 (no dependencies):** T00001, T00002
- **Group 2 (after Group 1):** T00003, T00005
- **Group 3 (after T00004):** T00006

### Recommended Order
1. T00001, T00002 (parallel)
2. T00003 (depends on T00001)
3. T00004 (depends on T00001, T00002)
4. T00005, T00006 (parallel, after T00004)

Dependency criteria:

• Shared data models or APIs
• Feature builds on another feature
• Infrastructure requirements
• Test dependencies

Step 4: Create Ticket Definitions

See references/ticket-workflow.md for complete ticket structure and formats.

For each new ticket:

1. Determine ticket number (T0000N format, zero-padded 5 digits)
2. Create directory docs/tickets/T0000N/
3. Create 1-definition.md with:

# T0000N: Feature Name

## Objective
What this ticket accomplishes.

## Background
Self-contained context from PRD (not just references).

## Requirements
- Requirement 1
- Requirement 2

## Out of Scope
- What this ticket does NOT include

## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2

4. Update docs/tickets/index.md:

## Active Tickets

| Ticket | Description | Status |
|--------|-------------|--------|
| T0000N | Feature Name | New |

Step 5: Verify

Check all planning docs and tickets are valid:

1. 00-overall-plan.md exists and not empty
2. tickets/index.md exists
3. All ticket directories have 1-definition.md
4. No empty definition files

If verification fails, fix issues and re-verify (max 3 retries).

Step 6: Commit

Stage and commit planning changes:

git add docs/2-current/*.md
git add docs/tickets/index.md
git add docs/tickets/T*/1-definition.md
git commit -m "Sync planning docs and ticket definitions"

Output

After running this skill:

• Planning docs updated with new tickets
• Ticket directories created with definitions
• docs/tickets/index.md updated
• Changes committed with descriptive message

Example Usage

User: Create tickets for unbuilt features
Assistant: [Checks for 99-discrepancies.md, then uses sync-planning skill]

User: Sync planning with discrepancies report
Assistant: [Uses sync-planning skill]

Full Sync Workflow

1. analyze-gaps    → generates 99-discrepancies.md
2. sync-prd        → updates PRD docs
3. sync-planning   → creates tickets for unbuilt features (this skill)

Relation to Other Skills

Skill	Purpose
analyze-gaps	Generates discrepancies report (run first)
sync-prd	Updates PRD docs (IMPLEMENTED_NOT_DOCUMENTED, DIVERGED, OUTDATED)
sync-planning	Creates tickets (DOCUMENTED_NOT_IMPLEMENTED) - this skill
project-manager	Coordinates ticket implementation