Workflow Challenger

Workflow Challenger Skill

Purpose

Act as a critical reviewer and devil's advocate at any stage of the feature workflow. This skill performs deep analysis to:

• Challenge assumptions and decisions
• Identify gaps and missing specifications
• Surface unanswered questions
• Verify coherence between documents and codebase
• Ensure nothing has been overlooked

Key principle: Better to surface issues early than discover them during implementation or testing.

When to Use This Skill

Use this skill:

• After completing CDC.md to verify specification completeness
• After research to challenge technical decisions
• After planning to verify plan coherence with requirements
• Before implementation to catch missing details
• After test failures to understand root causes
• Anytime something feels incomplete or uncertain
• When user wants a second opinion on approach

IMPORTANT: User Interaction

Use the AskUserQuestion tool when clarification is needed on identified gaps.

After analysis, use AskUserQuestion to:

• Confirm critical issues need resolution
• Get user input on ambiguous findings
• Prioritize which gaps to address first

AskUserQuestion:
  questions:
    - question: "I found that the CDC doesn't address error handling. How should we proceed?"
      header: "Gap Found"
      options:
        - label: "Add to CDC now"
          description: "Update the specification before continuing"
        - label: "Note for later"
          description: "Document as known gap, address during implementation"
        - label: "Not needed"
          description: "This case won't occur in practice"
      multiSelect: false

This ensures:

• User is aware of identified issues
• Clear decision-making on how to proceed
• Gaps are explicitly acknowledged or resolved

Analysis Sources

The challenger analyzes multiple sources to build comprehensive context:

1. Project Documentation

Look for documentation folders at project root:
- [DOC]-{ProjectName}/
- docs/
- documentation/
- .doc/
- wiki/

Read all relevant documentation to understand:

• Project architecture
• Business rules
• Existing conventions
• Historical decisions

2. Codebase Analysis

Analyze existing code to understand:
- Current implementation patterns
- Data models and schemas
- API contracts
- Service dependencies
- Configuration patterns

3. Workflow Deliverables

Review current workflow documents:
- CDC.md (specification)
- findings.md (research)
- Plan.md (implementation plan)
- test-plan.md (test strategy)

4. Obsidian/Knowledge Base

If Obsidian MCP is available:
- Search for related notes
- Find linked concepts
- Discover historical context

Challenge Workflow

Phase 1: Context Gathering

1. Identify current stage - What deliverable is being challenged?
2. Read the deliverable - Understand what has been documented
3. Explore project docs - Find [DOC]-* folders and read relevant files
4. Analyze codebase - Understand existing patterns and constraints
5. Build mental model - Synthesize all information

Example context gathering:
1. Read CDC.md for "email notifications" feature
2. Found [DOC]-Backend/ with architecture.md
3. Found existing NotificationService in codebase
4. Found EmailTemplate component already exists
5. Mental model: Feature partially exists, CDC doesn't mention this

Phase 2: Gap Analysis

Systematically check for gaps in each category:

2.1 Missing Requirements

• Are all user stories covered?
• Are edge cases addressed?
• Are error scenarios defined?
• Are non-functional requirements specified?

2.2 Unclear Specifications

• Are there ambiguous terms?
• Are there assumptions not validated?
• Are there "TBD" or placeholder sections?
• Are acceptance criteria measurable?

2.3 Incoherence Detection

• Does the document contradict itself?
• Does it contradict project documentation?
• Does it contradict existing codebase?
• Does it contradict other workflow documents?

2.4 Missing Context

• Is existing functionality acknowledged?
• Are dependencies identified?
• Are integration points clear?
• Is the scope realistic?

See references/gap-analysis-guide.md for detailed checklist.

Phase 3: Challenge Formulation

For each identified issue, formulate a clear challenge:

Structure:

## Challenge: [Title]

**Type:** Gap / Ambiguity / Incoherence / Missing Context
**Severity:** Critical / Major / Minor
**Location:** [Document section or code location]

**Observation:**
[What was found or missing]

**Question:**
[Specific question to resolve the issue]

**Recommendation:**
[Suggested resolution or investigation]

Example:

## Challenge: Existing Email System Not Addressed

**Type:** Missing Context
**Severity:** Critical
**Location:** CDC.md Section 4 (Functional Requirements)

**Observation:**
The CDC specifies creating an EmailService, but the codebase already
has `src/services/NotificationService.ts` with email capabilities.
The CDC doesn't mention whether to extend, replace, or ignore it.

**Question:**
Should we extend the existing NotificationService or create a
separate EmailService? What happens to existing email functionality?

**Recommendation:**
Update CDC to explicitly address the existing NotificationService.
Consider extending it rather than creating parallel functionality.

Phase 4: Coherence Verification

Cross-check between documents and reality:

CDC vs Codebase:

• Are referenced components real?
• Do proposed integrations make sense?
• Are technology choices consistent?

CDC vs Project Docs:

• Does it follow documented architecture?
• Does it respect documented constraints?
• Is terminology consistent?

Findings vs CDC:

• Does research address all CDC requirements?
• Are POC results aligned with specifications?
• Are chosen patterns appropriate?

Plan vs Findings:

• Does plan implement research recommendations?
• Are dependencies correctly sequenced?
• Is scope consistent?

Phase 5: Report Generation

Compile findings into a structured report:

# Challenge Report: [Deliverable Name]

**Date:** [Date]
**Stage:** [Specification / Research / Planning / etc.]
**Challenger:** Claude Code

## Summary

[Brief overview of findings]

- **Critical Issues:** X
- **Major Issues:** X
- **Minor Issues:** X

## Critical Issues

[Must be resolved before proceeding]

## Major Issues

[Should be resolved, but not blocking]

## Minor Issues

[Nice to address, low impact]

## Coherence Check

| Source A | Source B | Status | Notes |
|----------|----------|--------|-------|
| CDC | Codebase | ⚠️ | [Issue] |
| CDC | Project Docs | ✅ | Aligned |

## Questions for User

1. [Question 1]
2. [Question 2]

## Recommendations

1. [Recommendation 1]
2. [Recommendation 2]

## Conclusion

[Overall assessment and suggested next steps]

Challenge by Stage

Challenging CDC.md (Specification)

Focus on:

• Requirement completeness
• Scope clarity
• Acceptance criteria measurability
• Alignment with project architecture
• Existing functionality conflicts

Key questions:

• "Is this already partially implemented?"
• "Does this conflict with existing features?"
• "Are all personas addressed?"
• "What happens in failure scenarios?"

Challenging findings.md (Research)

Focus on:

• Technical decision rationale
• Alternative evaluation completeness
• POC validity
• Integration feasibility
• Risk identification

Key questions:

• "Why this approach over alternatives?"
• "Was the POC representative?"
• "Are performance implications understood?"
• "What could go wrong?"

Challenging Plan.md (Implementation)

Focus on:

• Step granularity appropriateness
• Dependency correctness
• Parallelization opportunities
• Missing steps
• Validation criteria clarity

Key questions:

• "Is this step too vague to implement?"
• "What if step X fails?"
• "Can these steps run in parallel?"
• "How do we know this step is complete?"

Challenging test-plan.md (Testing)

Focus on:

• Coverage completeness
• Test priority appropriateness
• Edge case coverage
• Performance test inclusion
• Realistic test scenarios

Key questions:

• "Are negative scenarios tested?"
• "Is this test redundant with another?"
• "What's the most likely failure mode?"
• "Are integration points tested?"

Context Discovery Patterns

Finding Project Documentation

# Common documentation locations
Glob: [DOC]-*/**/*.md
Glob: docs/**/*.md
Glob: documentation/**/*.md
Glob: *.md (root level)
Glob: .github/**/*.md

Finding Related Code

# Based on feature name/domain
Grep: "feature-keyword"
Glob: **/*Service*.ts
Glob: **/*Controller*.cs
Glob: **/models/**/*

Using Obsidian MCP

If Obsidian available:
- Search notes for feature keywords
- Find linked architecture decisions
- Discover related past implementations

Challenge Intensity Levels

Quick Review (5-10 min)

• Scan document structure
• Check for obvious gaps
• Verify key sections present
• Spot-check coherence

Standard Review (15-30 min)

• Full document read
• Cross-reference with codebase
• Check project documentation
• Formulate key questions

Deep Review (30-60 min)

• Comprehensive analysis
• Full codebase exploration
• All documentation reviewed
• Detailed challenge report

Tips for Effective Challenging

1. Be constructive - Goal is improvement, not criticism
2. Be specific - Vague concerns aren't actionable
3. Prioritize - Focus on critical issues first
4. Suggest solutions - Don't just identify problems
5. Consider context - Time/resource constraints matter
6. Trust but verify - Check claims against reality
7. Document findings - Create actionable report
8. Ask, don't assume - Formulate questions when uncertain

Integration with Workflow

The challenger can be invoked:

• Explicitly: User requests challenge review
• At transitions: Between workflow phases
• On demand: Anytime during development

Phase 0: Specification → [Challenge CDC] → Phase 1: Research
Phase 1: Research → [Challenge Findings] → Phase 2: Planning
Phase 2: Planning → [Challenge Plan] → Phase 3: Implementation
...

Bundled Resources

• references/challenge-checklist.md - Comprehensive checklist by stage
• references/gap-analysis-guide.md - Detailed gap analysis methodology