Workflow Reconciliation

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

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

```
Reconciliation Progress:
- [ ] Phase 1: Context Detection
- [ ] Phase 2: Rule Loading
- [ ] Phase 3: Gap Analysis
- [ ] Phase 4: Report Generation
- [ ] Phase 5: Remediation Execution
```

Phase 1: Context Detection

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

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

Phase 2: Rule Loading

Phase 3: Gap Analysis

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

Phase 4: Report Generation

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

Phase 5: Remediation Execution

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