workflow-reconciliation
Detect current workflow context, validate state file currency, and remediate gaps to prevent checkpoint amnesia.
When to Invoke This Skill
- 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.
Core Responsibilities
<orchestration_pattern> This skill follows a 5-phase pattern:
- Context Detection → Identify workflow, stage, plugin
- Rule Loading → Load expected state for workflow+stage
- Gap Analysis → Compare filesystem vs expected state
- Report Generation → Show gaps with proposed fixes
- Remediation → Execute user's chosen fix strategy
<progress_tracking> 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
</progress_tracking> </orchestration_pattern>
Phase 1: Context Detection
<context_detection enforcement="blocking"> <required_analysis> Detect current workflow context by analyzing:
<detection_method priority="1" source=".continue-here.md">
IF .continue-here.md exists in current plugin directory:
- Extract YAML frontmatter (workflow, stage, status, phase)
- This is authoritative source of workflow state
</detection_method>
<detection_method priority="2" source="PLUGINS.md">
IF plugin name provided as argument:
- Read PLUGINS.md entry for plugin
- Extract status emoji (💡 Ideated, 🚧 Stage N, ✅ Working, 📦 Installed)
</detection_method>
<detection_method priority="3" source="filesystem_analysis">
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+)
</detection_method></required_analysis>
IF unable to detect context: BLOCK with error showing detected values and suggest providing plugin name.Phase 2: Rule Loading
<reconciliation_rules> <rule_loading> 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}" </rule_loading>
<rule_application> 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 </rule_application> </reconciliation_rules>
Phase 3: Gap Analysis
<gap_analysis enforcement="blocking"> <validation_sequence enforce_order="true"> 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
<check order="2" category="file_existence" required="true">
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
</check>
<check order="3" category="state_file_currency" required="true">
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
</check>
<check order="4" category="git_status" required="true">
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
</check></validation_sequence>
<gap_aggregation> 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}]} </gap_aggregation>
Phase 4: Report Generation
<reconciliation_report> <report_generation> 1. Aggregate gap analysis results 2. Generate proposed actions based on gaps found 3. Format report with visual dividers 4. Display report to user </report_generation>
<checkpoint_protocol> After displaying report, MUST present decision menu and WAIT.
<decision_menu format="inline_numbered_list" forbidden_tool="AskUserQuestion">
Present options based on gap severity:
<menu_options category="no_gaps_found">
1. All good - return to workflow (recommended)
2. Show me the state files anyway
3. Force reconciliation (update timestamps)
4. Other
</menu_options>
<menu_options category="minor_gaps" condition="only_timestamp_drift">
1. Fix automatically - Update timestamps and commit
2. Show me the diffs first
3. Update .continue-here.md only
4. Skip reconciliation
5. Other
</menu_options>
<menu_options category="major_gaps" condition="missing_files_or_uncommitted">
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
</menu_options>
</decision_menu>
<blocking_wait>
WAIT for user response - NEVER auto-proceed.
</blocking_wait></checkpoint_protocol> </reconciliation_report>
Phase 5: Remediation Execution
<remediation_strategies> <shared_error_handling> For all strategies: If git operations fail, display error and return to decision menu. For persistent issues, suggest /research. </shared_error_handling>
Based on user's menu choice, execute appropriate strategy:
Reference Files
- reconciliation-rules.json - Workflow-specific expectations (includes commit message templates)
- handoff-formats.md -.continue-here.md structure per workflow
- reconciliation-examples.md - Example reports and outputs
Success Criteria
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