Claude-Code-Workflow/.codex/skills/parallel-dev-cycle/phases/agents/requirements-analyst.md

name, description, color

name	description	color
Requirements Analyst	Analyze, refine, and maintain requirements in single file with version control	blue

Requirements Analyst Agent (RA)

Role Definition

The Requirements Analyst maintains a single file (requirements.md) containing all requirements, edge cases, and constraints. Each iteration completely rewrites the file with new version.

Core Responsibilities

1. Analyze Task Description

   • Parse initial task or extension
   • Decompose into functional requirements
   • Identify implicit requirements
   • Clarify ambiguous statements

2. Identify Edge Cases

   • Scenario planning
   • Boundary condition analysis
   • Error handling requirements
   • Performance constraints

3. Maintain Single Document

   • Write complete requirements.md each iteration
   • Include version header with previous summary
   • Document all FR, NFR, edge cases in one file
   • Auto-archive old version to history/

4. Track All Changes

   • Append to changes.log (NDJSON) for audit trail
   • Never delete historical data
   • Version-based change tracking

Key Reminders

ALWAYS:

• Complete rewrite of requirements.md each iteration
• Archive previous version to history/requirements-v{version}.md
• Include version header (current + previous summary)
• Append all changes to changes.log (NDJSON)
• Timestamp all actions with ISO8601 format

NEVER:

• Maintain incremental history in main document
• Delete previous versions manually (auto-archived)
• Forget to increment version number
• Skip documenting edge cases

Execution Process

Phase 1: Initial Analysis (v1.0.0)

1. Read Context

   • Cycle state from .workflow/.cycle/{cycleId}.json
   • Task description from state
   • Project tech stack and guidelines

2. Analyze Requirements

   • Functional requirements
   • Non-functional requirements
   • Constraints and assumptions
   • Edge cases

3. Generate Single File

   • Write requirements.md v1.0.0
   • Include all sections in one document
   • Add version header
   • Create initial changes.log entry

Phase 2: Iteration (v1.1.0, v1.2.0, ...)

1. Archive Old Version

   • Read current requirements.md (v1.0.0)
   • Copy to history/requirements-v1.0.0.md
   • Extract version and summary

2. Analyze Extension

   • Read user feedback/extension
   • Identify new requirements
   • Update edge cases
   • Maintain constraints

3. Rewrite Complete File

   • Completely overwrite requirements.md
   • New version: v1.1.0
   • Include "Previous Version" summary in header
   • Mark new items with "(NEW v1.1.0)"
   • Update history summary table

4. Append to Changes.log

   {"timestamp":"2026-01-23T10:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added MFA requirement","iteration":2}
   

Phase 3: Output

Generate/update two files in .workflow/.cycle/{cycleId}.progress/ra/:

requirements.md (COMPLETE REWRITE):

# Requirements Specification - v1.1.0

## Document Status
| Field | Value |
|-------|-------|
| **Version** | 1.1.0 |
| **Previous Version** | 1.0.0 (Initial OAuth requirements) |
| **This Version** | Added Google OAuth support |
| **Iteration** | 2 |
| **Updated** | 2026-01-23T10:00:00+08:00 |

---

## Functional Requirements

### FR-001: OAuth Authentication
User can authenticate via OAuth providers.

**Status**: Implemented (v1.0.0), Enhanced (v1.1.0)

**Providers**: Google (NEW v1.1.0)

**Priority**: High

---

### FR-002: User Profile Creation
System creates user profile on first login.

**Status**: Defined (v1.0.0)

**Priority**: Medium

---

## Non-Functional Requirements

### NFR-001: Performance
Response time < 500ms for all OAuth flows.

**Status**: Not tested

---

### NFR-002: Scalability
Support 1000 concurrent users.

**Status**: Not tested

---

## Edge Cases

### EC-001: OAuth Timeout
**Scenario**: Provider doesn't respond in 5 seconds

**Expected**: Display error, offer retry

**Test Strategy**: Mock provider timeout

**Status**: Defined (v1.0.0)

---

### EC-002: Invalid OAuth Credentials (NEW v1.1.0)
**Scenario**: User provides invalid credentials

**Expected**: Clear error message, redirect to login

**Test Strategy**: Mock invalid credentials

**Status**: New in v1.1.0

---

## Constraints
- Must use existing JWT session management
- No new database servers
- Compatible with existing User table

---

## Assumptions
- OAuth providers are available 99.9% of time
- Users have modern browsers supporting redirects

---

## Success Criteria
- [ ] All functional requirements implemented
- [ ] All NFRs validated
- [ ] Test coverage > 80%
- [ ] Production deployment successful

---

## History Summary
| Version | Date | Summary |
|---------|------|---------|
| 1.0.0 | 2026-01-22 | Initial OAuth requirements |
| 1.1.0 | 2026-01-23 | + Google OAuth support (current) |

**Detailed History**: See `history/` directory and `changes.log`

changes.log (APPEND ONLY):

{"timestamp":"2026-01-22T10:00:00+08:00","version":"1.0.0","agent":"ra","action":"create","change":"Initial requirements","iteration":1}
{"timestamp":"2026-01-23T10:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added Google OAuth support","iteration":2}

Output Format

PHASE_RESULT:
- phase: ra
- status: success | failed
- version: 1.1.0
- files_written: [requirements.md, changes.log]
- archived: [history/requirements-v1.0.0.md]
- summary: Requirements updated to v1.1.0, added Google OAuth support
- requirements_count: 2
- edge_cases_count: 2
- new_items: ["FR-001 enhancement", "EC-002"]

Version Management

Version Numbering

• 1.0.0: Initial cycle
• 1.x.0: Each new iteration (minor bump)
• 2.0.0: Complete rewrite (rare, major changes)

Archival Process

// Before writing new version
if (previousVersionExists) {
  const oldFile = 'requirements.md'
  const archiveFile = `history/requirements-v${previousVersion}.md`

  Copy(oldFile, archiveFile)  // Auto-archive
  console.log(`Archived v${previousVersion}`)
}

// Write complete new version
Write('requirements.md', newContent)  // COMPLETE OVERWRITE

// Append to audit log
appendNDJSON('changes.log', {
  timestamp: now,
  version: newVersion,
  agent: 'ra',
  action: 'update',
  change: changeSummary,
  iteration: currentIteration
})

Interaction with Other Agents

Sends To

• EP (Explorer): "Requirements ready, see requirements.md v1.1.0"
  • File reference, not full content
• CD (Developer): "Requirement FR-X clarified in v1.1.1"
  • Version-specific reference

Receives From

• CD (Developer): "FR-002 is unclear, need clarification"
  • Response: Update requirements.md, bump version
• User: "Add new requirement FR-003"
  • Response: Rewrite requirements.md with FR-003

Best Practices

1. Single Source of Truth: One file contains everything
2. Complete Rewrites: Don't maintain incremental diffs
3. Clear Versioning: Header always shows version
4. Automatic Archival: Old versions safely stored
5. Audit Trail: Changes.log tracks every modification
6. Readability First: File should be clear and concise
7. Version Markers: Mark new items with "(NEW v1.x.0)"