workflow-reconciliation

• User explicitly runs /reconcile [PluginName?]
• Other skills detect state drift (plugin-workflow, ui-mockup)
• After subagent completion if handoff file missing
• When switching between workflows

NOT invoked for normal checkpoint completion (plugin-workflow handles that internally). ONLY for detected drift or explicit /reconcile command.

This skill follows a 5-phase pattern:

1. Context Detection → Identify workflow, stage, plugin

2. Rule Loading → Load expected state for workflow+stage

3. Gap Analysis → Compare filesystem vs expected state

4. Report Generation → Show gaps with proposed fixes

5. Remediation → Execute user's chosen fix strategy

Copy this checklist to track reconciliation progress:

```

Reconciliation Progress:

- [ ] Phase 1: Context Detection

- [ ] Phase 2: Rule Loading

- [ ] Phase 3: Gap Analysis

- [ ] Phase 4: Report Generation

- [ ] Phase 5: Remediation Execution

```

Detect current workflow context by analyzing:

IF .continue-here.md exists in current plugin directory:

- Extract YAML frontmatter (workflow, stage, status, phase)

- This is authoritative source of workflow state

IF plugin name provided as argument:

- Read PLUGINS.md entry for plugin

- Extract status emoji (💡 Ideated, 🚧 Stage N, ✅ Working, 📦 Installed)

IF no handoff file found:

- Analyze files created/modified in session

- Infer workflow from file patterns:

- .ideas/creative-brief.md → plugin-ideation

- .ideas/mockups/v*-ui.html → ui-mockup

- Source/*.cpp changes + CHANGELOG.md → plugin-improve

- plugins/*/CMakeLists.txt → plugin-workflow (Stage 1+)

BEFORE proceeding to gap analysis:

- MUST identify workflow name

- MUST identify current stage/phase

- MUST identify plugin name (if workflow is plugin-specific)

IF unable to detect context: BLOCK with error showing detected values and suggest providing plugin name.

1. Use jq to extract ONLY needed section from assets/reconciliation-rules.json

- Example: jq '.["plugin-workflow"].stages["2"]' reconciliation-rules.json

- Do NOT load entire 90-line file into context

2. Lookup workflow name from context detection

3. Lookup stage (for plugin-workflow) or phase (for other workflows) from context detection

4. Extract reconciliation rule for current workflow + stage/phase

5. If workflow not found in reconciliation-rules.json: BLOCK with error "Unknown workflow: {name}"

For current workflow and stage, validate:

- All state_files exist and are current

- All required_files exist

- PLUGINS.md status matches expected

- Git commit exists for this stage completion

For contract files (.ideas/*.md):

- Check if workflow is plugin-workflow AND stage is 1, 2, or 3

- If YES: WARN user that contracts are immutable during implementation

- Suggest completing current stage or rolling back to Stage 0

- BLOCK remediation of contract files during Stages 1-3

Use parallel Read tool calls to check all required_files simultaneously.

For each required_file in reconciliation rule:

- Check file exists at expected path (relative to plugins/{PluginName}/)

- Example: CMakeLists.txt → plugins/{PluginName}/CMakeLists.txt

- Record as GAP if missing

Read .continue-here.md YAML frontmatter:

- Extract: stage, phase, status, workflow, last_updated

- Compare to detected context

- Record as GAP if mismatch

Read PLUGINS.md entry for plugin:

- Extract status emoji

- Compare to expected status from reconciliation rule

- Record as GAP if mismatch

Run git status:

- Identify unstaged changes (modified, deleted)

- Identify staged but uncommitted changes

- Identify untracked files matching required_files pattern

- Record as GAP if uncommitted changes exist

Aggregate all gaps into structured report:

{

"file_existence_gaps": [

{"file": "CMakeLists.txt", "status": "missing", "expected_path": "plugins/{PluginName}/CMakeLists.txt"}

],

"state_currency_gaps": [

{"file": ".continue-here.md", "field": "stage", "current": "2", "expected": "3"}

],

"git_status_gaps": [

{"file": "Source/PluginProcessor.cpp", "status": "modified", "staged": false}

]

}

MUST complete all 4 check categories before generating report.

IF any check fails to execute: BLOCK with error.

1. Aggregate gap analysis results

2. Generate proposed actions based on gaps found

3. Format report with visual dividers

4. Display report to user

After displaying report, MUST present decision menu and WAIT.

Present options based on gap severity:

1. All good - return to workflow (recommended)

2. Show me the state files anyway

3. Force reconciliation (update timestamps)

4. Other

1. Fix automatically - Update timestamps and commit

2. Show me the diffs first

3. Update .continue-here.md only

4. Skip reconciliation

5. Other

1. Fix everything automatically - Create/update files and commit

2. Show me the diffs first - Preview before committing

3. Fix files only (no commit) - Update files but don't commit

4. Update .continue-here.md only - Minimal checkpoint

5. Skip reconciliation - I'll handle manually

6. Other

WAIT for user response - NEVER auto-proceed.

For all strategies: If git operations fail, display error and return to decision menu. For persistent issues, suggest /research.

Based on user's menu choice, execute appropriate strategy:

1. Update all state files with current context

2. Create missing required files (if possible)

3. Stage all changes: git add [files]

4. Commit with workflow-appropriate message

5. Verify commit succeeded: git log -1 --oneline

6. Confirm completion

1. For each file to be updated: show clear diff preview

2. Wait for user confirmation

3. Return to decision menu with modified options:

- Proceed with commit

- Abort reconciliation

- Other

1. Update state files (.continue-here.md, PLUGINS.md)

2. Verify files written successfully and YAML is valid

3. Do NOT stage or commit

4. Confirm files updated

1. Update .continue-here.md with current context

2. Verify file written successfully and YAML is valid

3. Leave other files unchanged

4. Confirm minimal checkpoint complete

1. Exit without changes

2. Warn user to reconcile manually before workflow resume

• [reconciliation-rules.json](assets/reconciliation-rules.json) - Workflow-specific expectations (includes commit message templates)
• [handoff-formats.md](references/handoff-formats.md) - .continue-here.md structure per workflow
• [reconciliation-examples.md](assets/reconciliation-examples.md) - Example reports and outputs

Reconciliation succeeds when:

State Files:

• .continue-here.md exists with current workflow, stage/phase, and timestamp
• PLUGINS.md status emoji matches expected state for current stage
• All required_files from reconciliation rule exist at expected paths

Git Status:

• No uncommitted workflow artifacts (all tracked files clean or committed)
• No staged but uncommitted changes
• Latest commit message follows workflow-appropriate convention

Workflow Continuity:

• Workflow can resume without context loss
• No checkpoint amnesia at workflow boundaries
• State files pass reconciliation-rules.json validation