Shared Patterns

Shared Command Patterns

Quick Reference

Command Integration

Commands reference these patterns by name rather than reimplementing. When developing or modifying /re:* commands, apply the relevant patterns to ensure consistent behavior across the plugin.

Pattern application:

• Load this skill when implementing command error handling or batch operations
• Reference pattern names in command instructions (e.g., "Apply Standard Recovery Flow")
• Use the AskUserQuestion structures defined here for consistent user interactions
• Follow the Batch Tracking summary format for operation reporting

For full implementation details, see references/implementation-details.md.

Overview

These four patterns provide consistent, reusable behavior across all /re:* commands:

1. Recovery Flow - Graceful error handling with user choice
2. Idempotency Check - Safe re-runs without duplicates
3. Batch Tracking - Clear operation summaries
4. Two-Layer Metadata - Complete GitHub Projects integration

Each pattern is designed for AI consumption—terse core definitions with detailed implementations in references/.

Standard Recovery Flow

When: Any gh CLI operation fails (network, auth, permissions, rate limit).

Options: Present via AskUserQuestion:

AskUserQuestion Structure:

header: "Operation Failed"
question: "[Operation] failed: [error message]. How would you like to proceed?"
options:
  - label: "Retry"
    description: "Attempt the operation again"
  - label: "Skip"
    description: "Skip this item and continue with the next"
  - label: "Check permissions"
    description: "Verify GitHub CLI authentication status"
  - label: "Stop"
    description: "Stop processing and show summary"

Variations:

• re:init: 3-option (no Skip) - single operation, nothing to skip
• re:discover-vision: Adds "Save draft" - preserve work on failure

Idempotency Check

When: Before creating any GitHub issue (vision, epic, story, task).

Flow:

1. Query existing: gh issue list --repo [repo] --label "type:[type]" --json number,title
2. Match: case-insensitive, trimmed title comparison
3. If match found → present options via AskUserQuestion

AskUserQuestion Structure:

header: "Duplicate Found"
question: "An issue titled '[title]' already exists (#[number]). How would you like to proceed?"
options:
  - label: "Skip"
    description: "Keep existing issue, don't create duplicate"
  - label: "Update"
    description: "Update the existing issue with new content"
  - label: "Create anyway"
    description: "Create new issue despite duplicate"

Tracking integration:

• Skip → add to skipped[] with existing issue number
• Update → add to updated[] after successful edit
• Create anyway → proceed to create, add to created[]

Batch Tracking

When: Processing multiple items (epics, stories, tasks, priority updates).

Lists: Initialize at command start:

• created[] – New items successfully created
• skipped[] – Items skipped (duplicates or user choice)
• updated[] – Existing items modified
• failed[] – Operations that failed (with error reason)

Summary Output Template:

## Summary

**Created:** [N] new [item-type]
- #[number] - [Title]
- #[number] - [Title]

**Updated:** [N] existing [item-type]
- #[number] - [Title] (updated [fields])

**Skipped:** [N] [item-type] (duplicates)
- [Title] (existing #[number])

**Failed:** [N] [item-type]
- [Title]: [error reason]

Display rules:

• Only show categories with count > 0
• Include issue numbers as #[number] links
• Show specific error reasons for failed items
• Order: Created → Updated → Skipped → Failed

Variation: re:prioritize adds partial[] for items where custom field updated but label failed.

Two-Layer Metadata Update

When: Setting Type, Priority, or Status on GitHub Project items.

Why two layers:

Operation order: Always update custom field first, then label.

Label mapping:

Tracking integration:

• Both succeed → add to updated[]
• Field succeeds, label fails → add to partial[] (non-blocking)
• Both fail → add to failed[]

Pattern Integration

Patterns work together in command workflows:

For each item to process:
  1. Idempotency Check → determines if create/update/skip
  2. Create or Update operation
     - On failure → Recovery Flow
     - On success → Two-Layer Metadata Update
  3. Track result in appropriate Batch Tracking list

After all items:
  4. Display Batch Tracking Summary

Cross-pattern data flow:

Pattern Usage by Command

Additional Resources

Reference Files

For detailed implementation guidance:

• references/implementation-details.md - Full implementation flows with code examples

Example Files

Working examples from actual commands:

• examples/pattern-usage.md - Pattern application in re:identify-epics

Converted and distributed by TomeVault — claim your Tome and manage your conversions.