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:

```markdown
## 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`

```markdown
## 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