---
roadcrew_template_name: "minimize-manual-steps.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# Cursor Command: minimize-manual-steps

**Temperature: 0.3-0.5** (Balanced creativity and precision)

## Purpose
Analyze roadcrew processes, scripts, or workflows to minimize manual interaction points. The goal is to require human input only upfront (configuration) and at verification checkpoints, with zero interruptions during execution.

## Activation
User says: "minimize manual steps" or "reduce manual work" or "streamline workflow"

## Analysis Framework

### 1. Map All Manual Interaction Points
Identify every point where a human must:
- Provide input (enter values, run multiple commands)
- Make decisions (choose options, select configurations)
- Verify results (check GitHub issues, confirm success)
- Navigate UIs (switch between terminal, GitHub, editor)
- Repeat actions (run multiple sequential commands)

### 2. Classify Each Interaction

For each interaction point, determine:

**A. Essential (Human-Only)**
- GitHub OAuth authorization (first-time setup)
- GitHub token creation and storage
- Strategic decisions (choosing release scope, prioritization)
- Final verification (confirming issues created correctly)
- Code review and approval

**B. Automatable**
- Configuration input (can read from `.env` or config files)
- GitHub token storage (can use environment variables)
- Sequential commands (can chain in single script)
- Error detection (can auto-check and retry)
- Issue creation from specs

**C. Eliminable**
- Redundant verifications (check once, not after every step)
- Manual file navigation (can script)
- Copy/paste between documents (can automate)
- Intermediate status checks (can log and summarize)
- Building TypeScript before each command (can auto-detect)

### 3. Optimization Strategies

#### Strategy 1: Front-Load Configuration
**Pattern**: Get all inputs upfront, store in configuration files
```
BEFORE: Multiple prompts during execution
AFTER: Single config file, read automatically
```

**Roadcrew Example:**
```bash
BEFORE:
  Enter owner: tailwind-ai
  Enter repo: roadcrew
  Enter milestone: v0.2.0
  Paste GitHub token: ghp_xxx...

AFTER:
  # One-time setup in .env
  GH_TOKEN=ghp_xxx...
  GITHUB_OWNER=tailwind-ai
  GITHUB_REPO=roadcrew
  
  # Or use git remote detection (auto-detects from .git/config)
  npm run scope-release
```

**Implementation:**
- Store GitHub token in environment variable
- Auto-detect owner/repo from git remote
- Read milestone from `memory-bank/releases/current-release.md`
- Script reads all config automatically

#### Strategy 2: Consolidate Interaction Points
**Pattern**: Combine multiple manual steps into single action
```
BEFORE: 
  1. npm run build
  2. npm run scope-release
  3. Review issues in GitHub UI
  4. npm run build
  5. npm run validate-release
  6. Review validation output

AFTER:
  1. npm run release-workflow
     - Auto-builds if needed
     - Scopes release
     - Creates issues
     - Validates automatically
     - Shows consolidated summary
```

**Roadcrew Example:**
- `ensure-built.js` already auto-builds when needed
- Could create meta-commands that chain multiple steps
- Single verification checkpoint at end

#### Strategy 3: Self-Healing Workflows
**Pattern**: Detect missing/broken state and auto-fix
```
if (not_built) {
  auto_build_typescript()
}
if (no_github_token) {
  show_helpful_setup_instructions()
}
proceed_with_task()
```

**Roadcrew Example:**
```typescript
// In any script that needs GitHub API:
async function ensureGitHubAuth() {
  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
  
  if (!token) {
    console.error('❌ GitHub token not found');
    console.log('📝 Setup instructions:');
    console.log('   1. Create token at https://github.com/settings/tokens');
    console.log('   2. Add to .env: GH_TOKEN=ghp_xxx...');
    console.log('   3. Or export: export GH_TOKEN=ghp_xxx...');
    process.exit(1);
  }
  
  return token;
}

// Already implemented: ensure-built.js checks and auto-compiles
```

#### Strategy 4: Checkpoint-Based Verification
**Pattern**: Run to completion, verify once at end
```
BEFORE: Verify step 1, verify step 2, verify step 3...
AFTER: Complete all steps → Single verification checkpoint
```

**Roadcrew Example:**
```
CURRENT FLOW:
  npm run scope-release      → Creates issues
  → User checks GitHub       → Manual verification
  npm run validate-release   → Validates structure

OPTIMIZED FLOW:
  npm run scope-release      → Creates issues + auto-validates
  → Shows consolidated report at end
  → Only one verification checkpoint
```

#### Strategy 5: Auto-Detect and Resume Operations
**Pattern**: Handle partial completion automatically
```
BEFORE: 
  Run → Error on issue 5 of 10 → User manually identifies where to resume
  → User re-runs with flags to skip completed issues
  
AFTER:
  Run once → Marks completed issues → Auto-resumes from failure point
  → User just re-runs same command
```

**Roadcrew Example:**
```typescript
// Issue creator could track state:
const processedIssues = new Set<string>(); // Track by epic/issue ID

async function createIssues(epics: Epic[]) {
  for (const epic of epics) {
    const epicKey = `epic:${epic.title}`;
    
    if (processedIssues.has(epicKey)) {
      console.log(`⏭️  Skipping already created: ${epic.title}`);
      continue;
    }
    
    try {
      await createEpic(epic);
      processedIssues.add(epicKey);
      saveProgress(); // Incremental save
    } catch (error) {
      console.error(`❌ Failed: ${epic.title}`);
      throw error; // User can re-run, skips completed
    }
  }
}
```

#### Strategy 6: Reduce Context Switching
**Pattern**: Keep user in one tool/terminal
```
BEFORE: 
  - Terminal → GitHub UI → Terminal → GitHub UI → Editor
  
AFTER:
  - Terminal (shows URLs) → GitHub UI (once to review)
```

**Roadcrew Example:**
```
BEFORE:
  1. Run scope-release (terminal)
  2. Open GitHub to check issues (browser)
  3. Back to terminal for next command
  4. Open GitHub again to verify (browser)

AFTER:
  1. Run scope-release (terminal)
  2. Script prints: "✅ Created 5 epics, 23 issues"
  3. Script prints: "🔗 View release: https://github.com/owner/repo/milestone/12"
  4. Single visit to GitHub for full review
```

### 4. Ideal Roadcrew Process Flow

```
┌─────────────────────────────────────────┐
│ PHASE 1: CONFIGURATION (Human Upfront) │
├─────────────────────────────────────────┤
│ • Create .env file (GH_TOKEN)           │
│ • Configure roadcrew.yml                │
│ • Write vision.md                       │
│ • Write specs                           │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│ PHASE 2: EXECUTION (Zero Interaction)  │
├─────────────────────────────────────────┤
│ • Auto-detects repo info from git       │
│ • Auto-builds TypeScript if needed      │
│ • Self-heals missing dependencies       │
│ • Creates all GitHub issues             │
│ • Logs progress incrementally           │
│ • Handles errors gracefully             │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│ PHASE 3: VERIFICATION (Human Checkpoint)│
├─────────────────────────────────────────┤
│ • Single verification command           │
│ • Clear success/failure indicators      │
│ • Links to review issues on GitHub      │
│ • Troubleshooting if failed             │
└─────────────────────────────────────────┘
```

### 5. Red Flags (Anti-Patterns)

❌ **Multiple manual commands in sequence**
- Breaks flow, easy to forget steps
- Solution: Create wrapper scripts that chain commands

❌ **Manual copy/paste between documents**
- Error-prone, tedious
- Solution: Scripts that read from specs and write to GitHub

❌ **Verification after every step**
- Time-consuming, interrupts momentum
- Solution: Batch operations, verify once at end

❌ **Instructions say "if X fails, manually do Y"**
- Forces user to troubleshoot
- Solution: Script should detect X and auto-do Y

❌ **Requiring domain knowledge mid-execution**
- User doesn't know what to choose
- Solution: Sensible defaults, override via config

❌ **Building before every command**
- Wastes time on repeated builds
- Solution: `ensure-built.js` checks timestamps (✅ already implemented)

❌ **Switching between multiple tools repeatedly**
- Lost mental state, slow
- Solution: Provide rich terminal output with summary URLs

### 6. Success Metrics

**Before Optimization:**
- Count: Number of commands user must run
- Time: Total time spent on manual steps
- Complexity: Number of different tools/context switches
- Error potential: Points where user can make mistakes

**After Optimization:**
- ✅ Commands reduced by >60%
- ✅ Execution time reduced by >40%
- ✅ Context switches reduced to 1-2
- ✅ Error points reduced by >70%

**Roadcrew Examples:**

*Release Creation Flow:*
```
BEFORE:
  1. npm run build
  2. npm run scope-release
  3. Check GitHub (context switch)
  4. npm run build
  5. npm run validate-release
  6. Check validation output
  7. npm run build
  8. npm run sync-release-status
  = 8 interactions, 3 context switches

AFTER:
  1. npm run release-workflow
     (auto-builds, scopes, validates, syncs)
  2. Review consolidated output with GitHub URLs
  3. Click URL to review issues
  = 3 interactions, 1 context switch
  
Reduction: 62% fewer interactions ✅
```

*Epic Implementation Flow:*
```
BEFORE:
  1. Read spec manually
  2. Copy epic structure to new file
  3. Fill in details manually
  4. Save to memory-bank/releases/
  5. Run scope-release
  6. Verify on GitHub
  = 6 manual steps

AFTER:
  1. Use /implement-epic command (Cursor)
     - AI reads spec automatically
     - AI generates epic with proper structure
     - AI saves to correct location
     - Auto-runs scope-release if confirmed
  2. Review on GitHub
  = 2 interactions
  
Reduction: 67% fewer steps ✅
```

### 7. Implementation Checklist

When applying this command:

- [ ] List all current manual interaction points
- [ ] Classify each as Essential/Automatable/Eliminable
- [ ] Design configuration-first approach (what goes in .env/config?)
- [ ] Identify self-healing opportunities (what can auto-detect/fix?)
- [ ] Consolidate sequential manual commands into wrapper scripts
- [ ] Add verification checkpoint at end (not throughout)
- [ ] Reduce context switching to minimum
- [ ] Update documentation to reflect new streamlined flow
- [ ] Test with fresh user perspective (zero prior knowledge)
- [ ] Measure: Count interactions before vs after

### 8. Roadcrew-Specific Opportunities

**Current Manual Steps to Automate:**

1. **Release Workflow** - Currently requires multiple commands:
   ```bash
   # Could consolidate:
   npm run release-workflow -- --milestone "v0.2.0"
   # Internally: builds → scopes → validates → syncs
   ```

2. **GitHub Authentication** - Better first-run experience:
   ```bash
   # Could add interactive setup:
   npm run setup
   # Guides through: token creation → .env setup → validation
   ```

3. **Spec → Epic → Issues** - Currently multi-step:
   ```bash
   # Could add end-to-end command:
   npm run implement-spec -- context/specs/my-spec.md
   # Internally: parses spec → generates epic → creates issues
   ```

4. **Feedback Processing** - Reduce manual recording classification:
   ```bash
   # Already automated, but could add:
   npm run process-feedback -- --auto-create-issues
   # Internally: process → classify → create GitHub issues automatically
   ```

5. **Repository Analysis** - Make it part of other workflows:
   ```bash
   # Instead of separate analyze-repo, auto-run when needed:
   npm run scope-release
   # Internally: checks if analysis current → re-analyzes if stale
   ```

## Example Usage

```
User: "I have to run 5 different npm commands to create a release. 
       Then I switch to GitHub to check the issues were created correctly.
       Then back to terminal for validation. Can we minimize manual steps?"

AI Response:
1. Analyze current workflow:
   - build → scope-release → check GitHub → build → validate-release
   - 5 terminal commands + 1 context switch

2. Identify automatable steps:
   - Build can auto-run when TypeScript is stale (ensure-built)
   - Validation can run automatically after scope-release
   - Can show GitHub URLs in terminal (reduce context switch)

3. Create consolidated command:
   npm run release-workflow
   
   This internally:
   - Auto-builds if needed (ensure-built.js)
   - Runs scope-release
   - Auto-validates
   - Shows summary with GitHub milestone URL
   
4. Result:
   - 1 command instead of 5 (80% reduction) ✅
   - 1 context switch instead of 2 (50% reduction) ✅
   - Same reliability, better UX ✅
```

## Implementation Examples

### Example 1: Auto-Building Before Commands
```typescript
// scripts/utils/ensure-built.ts
import { execSync } from 'child_process';
import { existsSync, statSync } from 'fs';

export function ensureBuilt(): void {
  // Check if dist/ exists and is newer than src/
  const needsBuild = !existsSync('dist') || isSourceNewer();
  
  if (needsBuild) {
    console.log('🔨 Building TypeScript...');
    execSync('npm run build', { stdio: 'inherit' });
  }
}

// Already implemented in roadcrew! ✅
```

### Example 2: Wrapper for Multi-Step Workflows
```typescript
// scripts/release-workflow.ts
import { ensureBuilt } from './utils/ensure-built.js';
import { scopeRelease } from './scope-release.js';
import { validateRelease } from './validate-release.js';
import { syncReleaseStatus } from './sync-release-status.js';

async function releaseWorkflow() {
  console.log('🚀 Starting release workflow...\n');
  
  // Auto-build if needed
  ensureBuilt();
  
  // Step 1: Scope release
  console.log('📋 Step 1/3: Scoping release...');
  const result = await scopeRelease();
  console.log(`✅ Created ${result.epics} epics, ${result.issues} issues\n`);
  
  // Step 2: Validate
  console.log('🔍 Step 2/3: Validating...');
  await validateRelease();
  console.log('✅ Validation passed\n');
  
  // Step 3: Sync status
  console.log('🔄 Step 3/3: Syncing status...');
  await syncReleaseStatus();
  console.log('✅ Status synced\n');
  
  // Summary
  console.log('═══════════════════════════════════');
  console.log('🎉 Release workflow complete!');
  console.log(`🔗 View milestone: ${result.milestoneUrl}`);
  console.log('═══════════════════════════════════');
}

releaseWorkflow().catch(console.error);
```

### Example 3: Self-Healing GitHub Auth
```typescript
// scripts/utils/github-auth.ts (enhanced)
import { Octokit } from '@octokit/rest';

export function getOctokit(): Octokit {
  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
  
  if (!token) {
    console.error('❌ GitHub token not found\n');
    console.log('📝 Setup required:');
    console.log('   1. Create token: https://github.com/settings/tokens/new');
    console.log('      - Required scopes: repo, read:org');
    console.log('   2. Add to .env file: GH_TOKEN=ghp_xxx...');
    console.log('   3. Or export in shell: export GH_TOKEN=ghp_xxx...');
    console.log('   4. Run this command again\n');
    console.log('💡 Quick start: npm run setup-github');
    process.exit(1);
  }
  
  // Validate token works
  const octokit = new Octokit({ auth: token });
  
  return octokit;
}

// Could add interactive setup:
// npm run setup-github
// → Prompts for token
// → Validates it works
// → Saves to .env
// → Shows success message
```