gh-propstreet-claude-powerpack/skills/ask-expert/EXAMPLES.md

Expert Consultation Examples

Complete usage examples for the ask-expert skill.

Complete Workflow Examples

Example 1: Bug Investigation

Scenario: JWT refresh token causing unexpected logouts

# 1. Create consultation document
cat > auth-bug-consultation.md << 'EOF'
# Expert Consultation: JWT Refresh Token Bug

## 1. Problem
Users are getting logged out unexpectedly after 15 minutes despite having valid refresh tokens.

## 2. Our Solution
Modified the token refresh logic in AuthService to use a sliding window approach instead of fixed expiration.

## 3. Concerns
- This couples authentication to session management
- Might introduce race conditions with concurrent requests
- Token refresh happens in middleware which feels wrong

## 4. Alternatives
- Separate auth service with dedicated refresh endpoint
- Use Redis for session management
- Switch to stateless JWTs

## 5. Architecture Overview

┌─────────┐ ┌──────────────┐ ┌───────────┐ │ Client │────▶│ Middleware │────▶│ Auth │ │ │◀────│ (Refresh) │◀────│ Service │ └─────────┘ └──────────────┘ └───────────┘ │ ▼ ┌──────────┐ │ Token │ │ Manager │ └──────────┘

---
# Complete Architecture Context
EOF

# 2. Extract code with size tracking
node scripts/extract-code.js \
  --track-size --output=auth-bug-consultation.md \
  --section="What Changed" \
  src/auth/AuthService.cs:diff \
  --section="Auth Flow (COMPLETE)" \
  src/auth/AuthController.cs \
  src/auth/TokenManager.cs \
  --section="Middleware" \
  src/middleware/AuthMiddleware.cs \
  --section="Tests" \
  tests/auth/AuthFlowShould.cs:1-150

# 3. Add expert questions
cat >> auth-bug-consultation.md << 'EOF'

---
# Expert Guidance Request

## Questions
1. Does our sliding window approach introduce security risks?
2. Better patterns for handling token refresh in middleware?
3. How to test race conditions effectively?
4. Should authentication and session management be separate concerns?

## Success Criteria
- Backward compatible with mobile clients
- No data loss during token refresh
- Clear security model
- Testable solution

**Please answer in English**
EOF

# 4. Verify size
wc -c auth-bug-consultation.md

Example 2: API Redesign

Scenario: Need expert review of new REST API design

# Use config file for complex extraction
cat > api-redesign-plan.json << 'EOF'
{
  "output": "api-redesign-consultation.md",
  "trackSize": true,
  "sections": [
    {
      "header": "Current API Design",
      "files": [
        "src/controllers/ApiController.cs",
        "src/models/ApiRequest.cs",
        "src/models/ApiResponse.cs"
      ]
    },
    {
      "header": "Service Layer",
      "files": [
        "src/services/ApiService.cs:1-200",
        "src/services/ApiService.Validation.cs"
      ]
    },
    {
      "header": "Test Coverage",
      "files": [
        "tests/ApiControllerShould.cs:100-300"
      ]
    }
  ]
}
EOF

node scripts/extract-code.js \
  --config=api-redesign-plan.json

Example 3: Architecture Review

Scenario: TypeScript strict mode migration

# 1. Write problem context
cat > typescript-strict-consultation.md << 'EOF'
# Expert Consultation: TypeScript Strict Mode Migration

## 1. Problem
Legacy codebase has `strict: false` in tsconfig.json. Need to enable strict mode without breaking production.

## 2. Our Solution
Incremental migration by file, starting with new code and migrating old files gradually.

## 3. Concerns
- 500+ files to migrate
- Some patterns don't work well with strict mode (dynamic property access)
- Team unfamiliar with strict mode patterns

## 4. Alternatives
- Big bang migration with dedicated sprint
- Stay on non-strict mode indefinitely
- Use strict mode only for new files

## 5. Architecture Overview
[Diagram showing file dependency graph]

---
# Complete Architecture Context
EOF

# 2. Batch extract multiple files efficiently
node scripts/extract-code.js \
  --track-size --output=typescript-strict-consultation.md \
  --section="Type Definitions" \
  src/types/payloads.ts src/types/responses.ts \
  --section="Core Files (COMPLETE)" \
  src/handlers/base-handler.ts \
  src/handlers/intents.ts \
  --section="Config" \
  tsconfig.json \
  --section="Example Migrated Files" \
  src/services/user.ts src/services/auth.ts

# 3. Add questions
cat >> typescript-strict-consultation.md << 'EOF'

---
# Expert Guidance Request

## Questions
1. Recommended migration order for 500+ files?
2. Common patterns that break in strict mode and their fixes?
3. Tooling to automate parts of the migration?
4. Testing strategy during migration?

## Success Criteria
- Zero runtime regressions
- Team can maintain strict mode going forward
- Migration completable in 2-3 sprints

**Please answer in English**
EOF

Extract-Code Script Usage

Basic Patterns

Extract full files:

node scripts/extract-code.js \
  src/Service.cs tests/ServiceTests.cs

Extract line ranges:

node scripts/extract-code.js \
  src/Service.cs:100-200 tests/ServiceTests.cs:50-75

Multiple ranges from one file:

node scripts/extract-code.js \
  src/Service.cs:1-30,86-213,500-600

Mix full files and ranges:

node scripts/extract-code.js \
  src/Models/User.cs src/Service.cs:100-150

Git Diff Patterns

Diff vs master (default):

node scripts/extract-code.js \
  src/Service.cs:diff

Explicit diff range:

node scripts/extract-code.js \
  src/Service.cs:diff=master..feature-branch \
  src/Helper.cs:diff=HEAD~3..HEAD

Recent changes:

node scripts/extract-code.js \
  src/Service.cs:diff=HEAD~5

Combine diffs with regular files:

node scripts/extract-code.js \
  src/Service.cs:diff \
  src/Tests.cs:100-200 \
  src/Models.cs

Size Tracking Patterns

Basic size tracking:

node scripts/extract-code.js \
  --track-size --output=consultation.md \
  src/Service.cs

With sections:

node scripts/extract-code.js \
  --track-size --output=doc.md \
  --section="Core Interfaces" \
  Interface.cs BaseClass.cs \
  --section="Domain Models" \
  Contact.cs Company.cs \
  --section="Tests" \
  Tests.cs:100-200

Incremental building (appends each time):

node scripts/extract-code.js \
  --track-size -o doc.md File1.cs

node scripts/extract-code.js \
  --track-size -o doc.md File2.cs  # Appends

node scripts/extract-code.js \
  --track-size -o doc.md File3.cs  # Appends again

Config File Patterns

Simple config:

{
  "output": "consultation.md",
  "trackSize": true,
  "sections": [
    {
      "header": "Core Implementation",
      "files": ["src/Service.cs", "src/Model.cs"]
    }
  ]
}

Complex config with diffs:

{
  "output": "feature-consultation.md",
  "trackSize": true,
  "sections": [
    {
      "header": "What We Changed",
      "files": [
        "src/Service.cs:diff",
        "src/Helper.cs:diff=master..feature-branch"
      ]
    },
    {
      "header": "Frontend Component (COMPLETE)",
      "files": ["src/components/MyComponent.vue"]
    },
    {
      "header": "Component Tests (COMPLETE)",
      "files": ["tests/components/MyComponent.test.ts"]
    },
    {
      "header": "Core Interfaces",
      "files": ["src/interfaces/IMyService.cs"]
    },
    {
      "header": "Domain Models",
      "files": [
        "src/models/MyModel.cs",
        "src/models/RelatedModel.cs"
      ]
    },
    {
      "header": "Service Implementation (Relevant Methods)",
      "files": ["src/services/MyService.cs:100-500"]
    }
  ]
}

Run config:

node scripts/extract-code.js \
  --config=extraction-plan.json

Size Tracking Output

The script shows real-time progress:

📄 consultation.md: 4.9 KB (existing)
[1/8] NetworkIndex.vue → +25.5 KB (30.4 KB / 125 KB, 24.3%)
[2/8] NetworkIndex.test.ts → +14.0 KB (44.4 KB / 125 KB, 35.5%)
[3/8] NetworkController.cs → +12.3 KB (56.7 KB / 125 KB, 45.4%)
[4/8] INetworkService.cs → +3.2 KB (59.9 KB / 125 KB, 47.9%)
[5/8] Contact.cs → +8.1 KB (68.0 KB / 125 KB, 54.4%)
[6/8] Company.cs → +7.4 KB (75.4 KB / 125 KB, 60.3%)
[7/8] NetworkService.cs → +9.2 KB (84.6 KB / 125 KB, 67.7%)
[8/8] Tests.cs → +2.7 KB (87.3 KB / 125 KB, 69.8%)
✅ Saved: 8 files to consultation.md (87.3 KB / 125 KB)

Warnings at thresholds:

⚠️  Approaching 100 KB    (at 100 KB)
⚠️  Very close to limit!  (at 115 KB)
❌ Exceeded 125 KB limit  (stops processing)

Traditional Redirection

You can also use traditional shell redirection:

node scripts/extract-code.js \
  src/Service.cs > expert-consultation.md

node scripts/extract-code.js \
  src/Tests.cs >> expert-consultation.md  # Append

Note: Without --track-size, you won't see progress or warnings.

Tips for Efficiency

1. Batch files together - One call is better than many
2. Use config files for complex extractions you'll repeat
3. Use full files when possible - better context for expert
4. Use diffs to show "what changed" concisely
5. Track size to avoid hitting 125 KB limit
6. Verify early - run wc -c to check size before adding more