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:

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

<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 `` </progresstracking> </orchestrationpattern>

Phase 1: Context Detection

<contextdetection enforcement="blocking"> <requiredanalysis> Detect current workflow context by analyzing:

<detectionmethod 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 </detectionmethod>

<detectionmethod 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) </detectionmethod>

<detectionmethod priority="3" source="filesystemanalysis"> 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+) </detectionmethod> </requiredanalysis>

<validation> 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. </validation> </context_detection>

Phase 2: Rule Loading

<reconciliationrules> <ruleloading> 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>

<ruleapplication> For current workflow and stage, validate: - All statefiles exist and are current - All requiredfiles exist - PLUGINS.md status matches expected - Git commit exists for this stage completion </ruleapplication> </reconciliation_rules>

Phase 3: Gap Analysis

<gapanalysis enforcement="blocking"> <validationsequence enforceorder="true"> <check order="1" category="contractimmutability" required="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>

<check order="2" category="fileexistence" required="true"> Use parallel Read tool calls to check all requiredfiles 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="statefilecurrency" 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="gitstatus" required="true"> Run git status: - Identify unstaged changes (modified, deleted) - Identify staged but uncommitted changes - Identify untracked files matching requiredfiles pattern - Record as GAP if uncommitted changes exist </check> </validation_sequence>

<gapaggregation> Aggregate all gaps into structured report: { "fileexistencegaps": [ {"file": "CMakeLists.txt", "status": "missing", "expectedpath": "plugins/{PluginName}/CMakeLists.txt"} ], "statecurrencygaps": [ {"file": ".continue-here.md", "field": "stage", "current": "2", "expected": "3"} ], "gitstatusgaps": [ {"file": "Source/PluginProcessor.cpp", "status": "modified", "staged": false} ] } </gap_aggregation>

<validation> MUST complete all 4 check categories before generating report. IF any check fails to execute: BLOCK with error. </validation> </gap_analysis>

Phase 4: Report Generation

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

<decisionmenu format="inlinenumberedlist" forbiddentool="AskUserQuestion"> Present options based on gap severity:

<menuoptions category="nogapsfound"> 1. All good - return to workflow (recommended) 2. Show me the state files anyway 3. Force reconciliation (update timestamps) 4. Other </menuoptions>

<menuoptions category="minorgaps" condition="onlytimestampdrift"> 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>

<menuoptions category="majorgaps" condition="missingfilesoruncommitted"> 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 </menuoptions>

</decision_menu>

<blockingwait> WAIT for user response - NEVER auto-proceed. </blockingwait> </checkpointprotocol> </reconciliationreport>

Phase 5: Remediation Execution

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

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

<strategy id="fixeverythingautomatically"> 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 </strategy>

<strategy id="showdiffsfirst"> 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 </strategy>

<strategy id="fixfilesonly"> 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 </strategy>

<strategy id="updatehandoffonly"> 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 </strategy>

<strategy id="skipreconciliation"> 1. Exit without changes 2. Warn user to reconcile manually before workflow resume </strategy> </remediationstrategies>

Reference Files

• [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

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