gh-coalesce-labs-catalyst-plugins-dev/commands/.auto-discover-pattern.md

Auto-Discovery Pattern for Workflow Commands

This document defines the standard pattern for commands that should automatically discover recent documents from workflow context.

The Problem

Commands have bash scripts to check workflow context, but they're suggestions for Claude - not guaranteed to execute. Users shouldn't have to paste file paths when we just created the file.

The Solution

Explicit, mandatory auto-discovery at the start of every workflow command.

Standard Pattern

1. Initial Response (REQUIRED)

Every workflow command must start with this EXACT pattern:

## Initial Response

When this command is invoked, IMMEDIATELY run this bash script BEFORE responding to the user:

```bash
# Auto-discover recent document from workflow context
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
  RECENT_DOC=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent <TYPE>)
  if [[ -n "$RECENT_DOC" ]]; then
    echo "📋 Auto-discovered recent <TYPE>: $RECENT_DOC"
    echo ""
  fi
fi

Replace <TYPE> with: handoffs, plans, research, or prs

CRITICAL: This bash script MUST be executed FIRST, before any other response.

### 2. Logic Flow (REQUIRED)

After running the auto-discovery script:

```markdown
1. **If user provided a file path as parameter**:
   - Use that path (user override)
   - Proceed with the command

2. **If no parameter provided but RECENT_DOC found**:
   - Show the user: "Found recent <TYPE>: $RECENT_DOC"
   - Ask: "Proceed with this document? [Y/n]"
   - If yes: proceed with RECENT_DOC
   - If no: ask for document path

3. **If no parameter and no RECENT_DOC found**:
   - List available documents (if applicable)
   - Ask user for document path

3. Command-Specific Examples

/resume-handoff

## Initial Response

IMMEDIATELY run this bash script BEFORE responding:

```bash
# Auto-discover recent handoff
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
  RECENT_HANDOFF=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent handoffs)
  if [[ -n "$RECENT_HANDOFF" ]]; then
    echo "📋 Auto-discovered recent handoff: $RECENT_HANDOFF"
    echo ""
  fi
fi

Then apply logic:

1. User provided path? → Use it
2. RECENT_HANDOFF found? → Ask to proceed with it
3. Nothing found? → Show available handoffs and ask

#### `/implement-plan`

```markdown
## Initial Response

IMMEDIATELY run this bash script BEFORE responding:

```bash
# Auto-discover recent plan
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
  RECENT_PLAN=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent plans)
  if [[ -n "$RECENT_PLAN" ]]; then
    echo "📋 Auto-discovered recent plan: $RECENT_PLAN"
    echo ""
  fi
fi

Then apply logic:

1. User provided path? → Use it
2. RECENT_PLAN found? → Ask to proceed with it
3. Nothing found? → Ask for plan path

#### `/create-plan`

Note: This command doesn't auto-discover (it creates new), but should reference recent research:

```markdown
## Context Gathering

After understanding the task, suggest recent research:

```bash
# Find recent research that might be relevant
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
  RECENT_RESEARCH=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent research)
  if [[ -n "$RECENT_RESEARCH" ]]; then
    echo "💡 Found recent research: $RECENT_RESEARCH"
    echo "Would you like me to reference this research in the plan?"
  fi
fi

## Key Principles

1. **Execute First, Ask Later**: Run auto-discovery BEFORE any user interaction
2. **Make it Visible**: Always show what was found with emoji indicator
3. **Allow Override**: User-provided paths always take precedence
4. **Graceful Fallback**: If nothing found, proceed with normal flow
5. **Confirm Before Proceeding**: Ask user to confirm auto-discovered document

## Commands That Need Auto-Discovery

### High Priority (Must Have)
- `/resume-handoff` → auto-find recent handoff ✅ (partially implemented)
- `/implement-plan` → auto-find recent plan ✅ (partially implemented)
- `/validate-plan` → auto-find plan being validated ❌ (missing)

### Medium Priority (Should Have)
- `/create-plan` → suggest recent research ❌ (missing)
- `/describe-pr` → find related plan/research ❌ (missing)

### Low Priority (Nice to Have)
- `/merge-pr` → reference PR description ❌ (missing)

## Testing Checklist

For each command with auto-discovery:

- [ ] Run bash script is FIRST thing command does
- [ ] Script output is visible to user
- [ ] User can override with explicit path
- [ ] User is asked to confirm auto-discovered doc
- [ ] Graceful fallback if nothing found
- [ ] Works with workflow context from hooks

## Implementation Status

| Command | Auto-Discovery | Status | Notes |
|---------|---------------|--------|-------|
| `/resume-handoff` | handoffs | 🟡 Partial | Has script but not explicit enough |
| `/implement-plan` | plans | 🟡 Partial | Has script but not explicit enough |
| `/validate-plan` | plans | ❌ Missing | Needs implementation |
| `/create-plan` | research (suggest) | ❌ Missing | Should offer to reference |
| `/describe-pr` | plans | ❌ Missing | Could auto-reference plan |

## Next Steps

1. Update `/resume-handoff` with explicit pattern
2. Update `/implement-plan` with explicit pattern
3. Add auto-discovery to `/validate-plan`
4. Add research suggestion to `/create-plan`
5. Test full workflow: research → plan → implement → validate