# Sync Planning

> 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.

- Skill: `majiayu000/sync-planning` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/sync-planning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/sync-planning/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/sync-planning

---


# 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:

```markdown
## 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:

```markdown
# 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`:

```markdown
## 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:

```bash
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 |