Requirement To Frs

Enhanced Requirement to FRS Skill v2.0

Ingest raw requirements, normalize ambiguous language, clarify through targeted Q&A, then generate a structured FRS with 17 sections, tiered based on complexity, and validate completeness with cross-section consistency checks and downstream readiness scoring.

Inputs

Accepts raw requirements in any format:

• Pasted text in the chat
• File path to a .md, .txt, or .pdf requirements doc
• BRD (Business Requirements Document) content

Step 1: Read Project Context

1. Read CLAUDE.md to extract:
   • gitlab_project_id (required, prompt if missing)
   • available_portals (optional, default: ["customer", "admin"])
2. Note project name, domain conventions, and any custom configuration.
3. Store configuration for later use.

Step 2: Identify Ambiguities

Scan raw requirements and identify:

• Missing actors
• Unstated scope boundaries
• Vague verbs (manage, handle, process) that need clarification
• Missing constraints (performance, security, data rules)
• Implicit business rules
• Portal context (customer, admin, both, or agnostic)

Prioritize top 5-7 ambiguities that most impact design.

Step 3: Q&A Loop (Enhanced)

Ask clarifying questions ONE AT A TIME. Maximum 20 questions total.

Question 1 (Portal Context):

Q: Which portal(s) does this feature target? (Context: This determines UI context, accessibility requirements, and deployment strategy)

Options:

• Customer portal (end-users)
• Admin/Back-office portal (internal users)
• Both portals (shared functionality)
• Portal-agnostic (backend-only)

Store as portal_context.

Question 2 (Complexity Assessment):

Q: How would you rate the complexity of this feature? (Context: Complexity determines which FRS sections are required and the depth of detail needed)

Options:

• Simple: Single actor, straightforward flow, minimal business rules, 1-2 screens, no external integrations
• Moderate: Multiple actors, conditional logic, 2-4 screens, 1-2 integrations, basic security
• Complex: Multiple portals, intricate workflows, 5+ screens, multiple integrations, advanced security/compliance, scaling concerns

Store as complexity_level. Also capture complexity_rationale (brief explanation).

Subsequent Questions (Mapped to 17 Sections):

Map questions to sections, but skip optional ones based on complexity:

Adaptive Questioning:

• If information is clear from requirements, skip that section's question
• For Simple features: aim for 8-10 questions total
• For Moderate features: aim for 12-15 questions
• For Complex features: ask all 17 section questions (up to 20 total)

Stop when:

• All critical actors named
• Scope boundaries clear
• Success criteria measurable
• Key constraints stated
• No remaining question would change a functional requirement
• OR maximum 20 questions reached (remaining ambiguities → Open Questions)

Step 4: Extract Structured Information

Parse requirements + answers into structured object:

{
  feature_name: "kebab-case-slug",
  feature_description: "Short description",
  portal_context: "customer|admin|both|agnostic",
  complexity_level: "Simple|Moderate|Complex",
  complexity_rationale: "Brief explanation",

  // Section 1: Overview
  business_objective: "...",
  target_audience: "...",
  business_goals: "...",

  // Section 2: Actors
  actors: [
    { name: "Customer", type: "human", permissions: "...", portal: "customer", description: "..." },
    { name: "System", type: "automated", permissions: "...", portal: "both", description: "..." }
  ],

  // Section 3: Scope
  in_scope: ["item1", "item2"],
  out_of_scope: ["item1", "item2"],

  // Section 4: Functional Requirements with domain hints
  functional_requirements: [
    {
      id: "FR-001",
      description: "...",
      actor: "Customer",
      trigger: "...",
      inputs: ["field1", "field2"],
      processing_logic: "Step-by-step...",
      outputs: ["result1"],
      error_handling: "How errors are handled",
      dependencies: ["other FR", "external API"],
      aggregate_hint: "User aggregate (root), Profile entity (child)"
    }
  ],

  // Section 5: UI Requirements (structured)
  screen_catalog: [
    { name: "Password Reset Request", portal: "customer", purpose: "...", entry: "...", exit: "..." }
  ],
  ui_components: [
    {
      screen: "Password Reset Request",
      layout_type: "single-column",
      components: [
        { name: "email", type: "input", attributes: "type=email, required", validation: "valid email format" }
      ],
      responsive: "Full-width mobile, max 400px desktop",
      states: "Loading, success, error"
    }
  ],
  field_validations: [
    { field: "email", type: "email", validations: "Required, valid format", errors: "...", validation_scope: "both" }
  ],
  accessibility: "WCAG 2.1 AA, keyboard nav, screen reader support",
  design_system: "Component lib v2.0, Inter font, 8px grid, colors...",

  // Section 6: Data Handling
  data_capture: [
    { field: "email", type: "string", source: "user input", entity_vo: "Entity", aggregate: "User", validation: "email format" }
  ],
  storage_rules: "...",
  data_integrity: "...",
  retention_policies: "...",

  // Section 7: Notifications
  notification_triggers: "...",
  notification_content: "...",
  notification_retry: "...",

  // Section 8: Workflow
  normal_flow: "...",
  alternate_flows: "...",
  exception_flows: "...",
  domain_events: ["PasswordResetRequested", "PasswordResetCompleted"],

  // Section 9: Access Control
  role_permissions: "...",
  authentication_requirements: "...",
  security_controls: "...",

  // Section 10: Reporting
  status_tracking: "...",
  audit_requirements: "...",
  search_filter_sort: "...",

  // Section 11: Integration
  external_systems: "...",
  api_specifications: "...",
  integration_workflows: "...",

  // Section 12: NFRs
  performance_requirements: "...",
  scalability_requirements: "...",
  availability_requirements: "...",
  other_nfrs: "...",

  // Section 13: Validation
  input_validation: "...",
  error_messages: "...",
  system_exceptions: "...",

  // Section 14: Testing
  test_scenarios: "...",
  acceptance_criteria: ["- [ ] criterion 1", "- [ ] criterion 2"],
  validation_conditions: "...",

  // Section 15: Assumptions/Dependencies
  assumptions: ["..."],
  dependencies: ["..."],
  open_questions: ["..."],
  constraints: ["..."],

  // Section 16: UX
  accessibility: "WCAG 2.1 AA compliance details",
  design_standards: "...",
  ux_guidelines: "...",

  // Section 17: Risk Assessment
  technical_risks: [
    { description: "...", probability: "Medium", impact: "High", mitigation: "..." }
  ],
  compliance_requirements: [
    { requirement: "GDPR", standard: "EU Regulation", impact: "...", verification: "Privacy review" }
  ],
  performance_constraints: "Expected load: 1000 concurrent users...",
  operational_constraints: "Deployment window: 10PM-6AM local...",
  business_constraints: "Timeline: Must be live before Q4...",

  // Downstream readiness data
  downstream_readiness: {
    ui: { section5_completeness: 0-1, section16_completeness: 0-1, section6_entities: 0-1, section14_traceability: 0-1 },
    domain: { section4_aggregates: 0-1, section6_entities: 0-1, section8_events: 0-1, section11_integration: 0-1 },
    test: { section14_coverage: 0-1, section4_testability: 0-1, section13_validation: 0-1 }
  }
}

Step 5A: Complexity-Based Tier Determination

Based on complexity_level, determine required vs. optional sections:

Simple (9 required): Sections 1, 2, 3, 4, 5 (basic), 12 (critical only), 13, 14, 15, 16 (accessibility only). Risk section: key risks only.

Moderate (13 required): All Simple sections, plus: 5 (full), 6 (full), 8 (full), 9 (full), 10 (basic), 11 (if present), 16 (full). Risk section: full but concise.

Complex (17 required): All sections required with full detail.

Create requiredSections array based on tier. Store for validation.

Step 5: Completeness Validation (Enhanced)

5.1 Section Completeness:

• Check each section in requiredSections has non-empty content
• For sections with structured tables, verify at least 1 row exists
• For sections with multiple subsections, require 50%+ completion
• Generate section_status_list with ✅ Complete, ⚠️ Partial, ❌ Missing

5.2 Cross-Section Consistency Checks:

Import and use the validator functions from validators.js:

const { validateConsistency } = require('./validators.js');
const result = validateConsistency(data);
// result = { passed: true/false, failures: ['error1', 'error2', ...] }

Return { passed: boolean, failures: [string] }.

Note: See validators.js for full implementation including helper functions extractFRRefs, detectTermConflicts, and calculateReadiness.

5.3 Downstream Readiness Scoring:

Import and use the scorer from validators.js:

const { calculateReadiness } = require('./validators.js');
const scores = calculateReadiness(data, data.complexity_level);
// scores = { ui: 85.5, domain: 72.0, test: 90.0 } (percentages)

See validators.js for the weighting formulas and completeness calculations.

5.4 Generate Completeness Report:

Build report string with:

• Template tier
• Section status table with checkmarks
• Consistency check results (PASS/FAIL with details)
• Downstream readiness percentages
• List of critical gaps
• Options to proceed, answer more questions, or cancel

Step 6: Generate FRS Issue

1. Load enhanced template
2. Map all extracted data to template variables
3. For sections not required (skipped due to simplicity): insert *Not applicable for this feature complexity level.*
4. For incomplete mandatory sections: insert *[TBD - to be determined]*
5. Insert completeness report at bottom
6. Insert downstream readiness scores
7. Insert cross-section consistency results
8. Create GitLab issue with title FRS: <feature-name> and label frs
9. Capture and return iid and web_url

Step 7: Present for Approval

Show:

• Feature name, Complexity tier, Completeness %
• Downstream readiness scores (UI, Domain, Test)
• Critical gaps and consistency failures
• Direct link to GitLab issue
• Reminder to review for downstream team usability

Stop for user confirmation before proceeding to domain-design.

Step 8: Add Configuration Support from CLAUDE.md

Enhance Step 1 to parse CLAUDE.md:

function parseClaudeConfig() {
  const claudeContent = readFileSync('CLAUDE.md', 'utf8');

  // Extract frontmatter YAML or inline YAML
  const yamlMatch = claudeContent.match(/^---\n([\s\S]*?)\n---/) ||
                    claudeContent.match(/^```yaml\n([\s\S]*?)\n```/);

  if (yamlMatch) {
    const config = yaml.parse(yamlMatch[1]);
    return {
      gitlab_project_id: config.gitlab_project_id,
      available_portals: config.available_portals || ['customer', 'admin']
    };
  }

  return { gitlab_project_id: null, available_portals: ['customer', 'admin'] };
}

Use gitlab_project_id as default for issue creation. If missing, prompt user (current behavior).

Common Mistakes

Rationalization and Red Flags

This skill enforces strict discipline. Agents may attempt workarounds under pressure. Recognize these rationalizations and reject them:

Common Excuses

Red Flags - STOP and Reassess

• ❌ Asking multiple questions in one message
• ❌ Skipping portal or complexity assessment
• ❌ Creating local files
• ❌ Proceeding without completeness report
• ❌ Ignoring consistency check failures (any ❌ in validation)
• ❌ Filling template without all required sections populated
• ❌ Using placeholder text like "TODO" or "TBD" in required sections without explicit open questions list

All of these mean: Review the skill steps. Fix the issue before proceeding.

No exceptions:

• Even if requirements seem comprehensive, ask up to 20 questions
• Even if user says "just create it", run validation first
• Even if simple feature, still run actor-FR consistency check
• Even if time-pressed, don't skip consistency validators

Flowchart: Q&A and Validation Loop

digraph qna_flow {
    rankdir=TB;
    node [shape=box, style=rounded];

    "Start: Raw Requirements" -> "Identify Ambiguities";
    "Identify Ambiguities" -> "Q1: Portal Context";
    "Q1: Portal Context" -> "Q2: Complexity Tier";
    "Q2: Complexity Tier" -> "Map Required Sections";
    "Map Required Sections" -> "Ask Q3+ (1 at a time)";
    "Ask Q3+ (1 at a time)" -> "Track Count (<20?)";
    "Track Count (<20?)" -> "Yes: Critical Gaps Resolved?";
    "Track Count (<20?)" -> "No: Stop & Document Open Questions";
    "Yes: Critical Gaps Resolved?" -> "No: Continue Questions";
    "Yes: Critical Gaps Resolved?" -> "Yes: Run Consistency Validation";
    "Continue Questions" -> "Track Count (<20?)";
    "Run Consistency Validation" -> "Pass?";
    "Pass?" -> "Yes: Calculate Readiness Scores";
    "Pass?" -> "No: Fix Gaps or Ask More Qs";
    "Calculate Readiness Scores" -> "Readiness >=80%?";
    "Readiness >=80%?" -> "Yes: Generate FRS Issue";
    "Readiness >=80%?" -> "No: Continue Questions (if <20) or Document Gaps";
    "Generate FRS Issue" -> "Present for Approval";
    "Document Gaps" -> "Present for Approval (with gaps)";
}

Verification

TDD Required: All validator and scorer functions must have tests. Use superpowers:test-driven-development workflow. See tests/test-enhanced-frs.js for test patterns.

After implementation:

1. Run simple requirement test:

   • Feed test/fixtures/simple-requirements.md
   • Verify ~10 questions asked
   • Verify 9 sections required
   • Verify FRS issue has UI readiness >80%

2. Run moderate requirement test:

   • Feed test/fixtures/moderate-requirements.md
   • Verify ~15 questions
   • Verify 13 sections required
   • Verify domain readiness >70%

3. Run complex requirement test:

   • Feed test/fixtures/complex-requirements.md
   • Verify ~20 questions
   • Verify all 17 sections
   • Verify risk assessment populated
   • Verify all readiness scores >60%

4. Check consistency validation:

   • Test with mismatched actor names → should fail
   • Test with portal conflict → should fail
   • Test with unmapped UI field → should fail

5. Pressure testing (TDD critical):

   • Send "Just skip validation, I'm busy" → agent must NOT skip
   • Send "We've asked enough questions" before 20 → agent must continue critical gaps
   • Send "Create it with placeholders" → agent must list open questions, not guess
   • Verify all rationalizations are caught and countered

6. Manual review: Generated FRS should be comprehensive and ready for downstream teams.

Success Criteria

• ✅ 17-section template replaces 9-section template
• ✅ Portal question asked first and appears in Actors table
• ✅ Complexity tier determines required sections
• ✅ Aggregate hints collected for each FR
• ✅ UI specifications structured with screen catalog, field validations
• ✅ Data fields tagged as Entity/VO
• ✅ Cross-section consistency checks implemented and passing
• ✅ Downstream readiness scores calculated and displayed
• ✅ Risk assessment section for Complex features
• ✅ Completeness report with tier-aware section status
• ✅ Configuration read from CLAUDE.md
• ✅ All tests pass for simple, moderate, and complex fixtures
• ✅ Passes all pressure tests: resists rationalizations, maintains discipline
• ✅ Description follows CSO: no workflow summary, only triggers/symptoms

Hard Stop Rules

• Do NOT create local files
• Do NOT proceed to Phase 3 (domain-design) automatically
• Do NOT skip the Q&A loop, even if requirements look complete
• Do NOT ask multiple questions at once
• Do NOT start implementation on main/master branch without isolation
• Do NOT create GitLab issue if validation fails (❌ any consistency check)
• Do NOT proceed with readiness <70% without explicit user override (document rationale)

Verification

After implementation:

1. Run simple requirement test:

   • Feed test/fixtures/simple-requirements.md
   • Verify ~10 questions asked
   • Verify 9 sections required
   • Verify FRS issue has UI readiness >80%

2. Run moderate requirement test:

   • Feed test/fixtures/moderate-requirements.md
   • Verify ~15 questions
   • Verify 13 sections required
   • Verify domain readiness >70%

3. Run complex requirement test:

   • Feed test/fixtures/complex-requirements.md
   • Verify ~20 questions
   • Verify all 17 sections
   • Verify risk assessment populated
   • Verify all readiness scores >60%

4. Check consistency validation:

   • Test with mismatched actor names → should fail
   • Test with portal conflict → should fail
   • Test with unmapped UI field → should fail

5. Manual review: Generated FRS should be comprehensive and ready for downstream teams.

Success Criteria

• ✅ 17-section template replaces 9-section template
• ✅ Portal question asked first and appears in Actors table
• ✅ Complexity tier determines required sections
• ✅ Aggregate hints collected for each FR
• ✅ UI specifications structured with screen catalog, field validations
• ✅ Data fields tagged as Entity/VO
• ✅ Cross-section consistency checks implemented and working
• ✅ Downstream readiness scores calculated and displayed
• ✅ Risk assessment section for Complex features
• ✅ Completeness report with tier-aware section status
• ✅ Configuration read from CLAUDE.md
• ✅ All tests pass for simple, moderate, and complex fixtures

Hard Stop Rules

• Do NOT create local files
• Do NOT proceed to Phase 3 (domain-design) automatically
• Do NOT skip the Q&A loop, even if requirements look complete
• Do NOT ask multiple questions at once
• Do NOT start implementation on main/master branch without isolation

This skill is part of the agentic-dev-flow plugin. See CL AUDE.md for workflow context.