Skip to main content

FR/BR Intake Process Analysis Report

Task: E4:S02:T01 – Analyze current FR/BR intake process and requirements
Date: 2025-12-02
Author: AI Agent (Auto)
Status: ✅ COMPLETE

Executive Summary​

This report analyzes the current state of Feature Request (FR) and Bug Report (BR) intake processes in the ai-dev-kit repository and identifies requirements for a systematic intake flow that converts FRs/BRs into Kanban Tasks.

Key Findings:

  • ✅ Policy exists: FR/BR → Task → Story → Epic flow is defined in Kanban governance policy
  • ❌ Process gap: No systematic intake process or templates exist
  • ❌ Documentation gap: No step-by-step guide for converting FRs/BRs to Tasks
  • ❌ Tooling gap: No templates or forms for FR/BR intake

Recommendation: Implement a complete intake system with templates, decision flows, and documentation.

1. Current State Analysis​

1.1 Policy Foundation​

Existing Policy:

  • Location: packages/frameworks/kanban/policies/kanban-governance-policy.md (framework)
  • Location: docs/project-management/rituals/policy/kanban-governance-policy.md (dev-kit implementation)

Key Rules Defined:

  1. FR/BR Source of Truth:

    • Every FR and BR MUST result in at least one Kanban Task
    • Tasks must live under a Story
    • Stories must live under an Epic (once epics are in use)

  2. FR/BR → Task → Story → Epic Flow (Canonical Rule):

    1. FR/BR arrives (issue tracker, support channel, notes, etc.)
    2. Check for existing Story that matches FR/BR scope
       → If found: create new Task under that Story
    3. If no Story exists:
       → Create new Story under appropriate Epic
    4. If no Epic exists:
       → Create new, conceptually broad Epic
       → Create Story under that Epic
       → Create Task under that Story

  3. Versioning Alignment:

    • Tasks map to TASK component in RC.EPIC.STORY.TASK+BUILD
    • Stories map to STORY component
    • Epics map to EPIC component

1.2 Current Gaps​

Missing Components:

  1. No Intake Templates:

    • ❌ No FR template/form
    • ❌ No BR template/form
    • ❌ No standardized format for capturing FR/BR details

  2. No Decision Flow:

    • ❌ No decision tree/flowchart for Story matching
    • ❌ No criteria for Epic matching/creation
    • ❌ No guidance on when to create new vs. use existing

  3. No Process Documentation:

    • ❌ No step-by-step intake guide
    • ❌ No worked examples
    • ❌ No troubleshooting guide

  4. No Tooling:

    • ❌ No automated intake scripts
    • ❌ No validation checks
    • ❌ No integration with issue trackers (if applicable)

  5. No Agent/User Guides:

    • ❌ No guide for AI agents processing FRs/BRs
    • ❌ No guide for human users submitting FRs/BRs

2. Requirements Analysis​

2.1 Functional Requirements​

FR-1: Intake Templates

  • Must provide structured format for FR submission
  • Must provide structured format for BR submission
  • Must capture all necessary information for Task creation
  • Must align with Kanban template structure

FR-2: Decision Flow

  • Must provide clear decision tree for Story matching
  • Must define criteria for Epic matching/creation
  • Must handle edge cases (ambiguous scope, multiple epics, etc.)
  • Must be visual and easy to follow

FR-3: Process Documentation

  • Must provide step-by-step guide
  • Must include worked examples for common scenarios
  • Must document integration with versioning
  • Must document integration with Release Workflow

FR-4: User Guides

  • Must provide agent-friendly guide (for AI assistants)
  • Must provide user-friendly guide (for human users)
  • Must include quick reference/cheat sheet
  • Must include troubleshooting section

2.2 Non-Functional Requirements​

NFR-1: Usability

  • Process must be easy to follow (5-10 minutes for simple cases)
  • Templates must be self-explanatory
  • Decision flow must be clear and unambiguous

NFR-2: Consistency

  • Must align with existing Kanban governance policy
  • Must align with versioning schema (RC.EPIC.STORY.TASK+BUILD)
  • Must align with Release Workflow requirements

NFR-3: Maintainability

  • Templates must be easy to update
  • Process must be documented in framework package (for reuse)
  • Examples must be kept current

NFR-4: Traceability

  • Must maintain link from FR/BR to Task
  • Must maintain link from Task to Story
  • Must maintain link from Story to Epic
  • Must support forensic traceability

2.3 Integration Requirements​

INT-1: Kanban Integration

  • Must create Tasks using Kanban Task structure
  • Must create Stories using Kanban Story template
  • Must create Epics using Kanban Epic template
  • Must update Kanban board appropriately

INT-2: Versioning Integration

  • Must ensure Task maps to TASK in version
  • Must ensure Story maps to STORY in version
  • Must ensure Epic maps to EPIC in version
  • Must follow versioning policy rules

INT-3: Release Workflow Integration

  • Must ensure Tasks are compatible with RW
  • Must ensure version numbers align with RW expectations
  • Must ensure Kanban docs are updated by RW

3. Use Cases​

3.1 Use Case 1: Simple FR → Existing Story​

Actor: User/Agent
Precondition: FR arrives, matching Story exists
Flow:

  1. User/Agent receives FR
  2. User/Agent searches for existing Story
  3. Story found that matches FR scope
  4. User/Agent creates new Task under existing Story
  5. Task is added to Story's task checklist
  6. Version is determined: RC.EPIC.STORY.{NEXT_TASK}+1

Postcondition: Task created, linked to Story, version assigned

3.2 Use Case 2: FR → New Story (Existing Epic)​

Actor: User/Agent
Precondition: FR arrives, no matching Story, but Epic exists
Flow:

  1. User/Agent receives FR
  2. User/Agent searches for existing Story
  3. No matching Story found
  4. User/Agent identifies appropriate Epic
  5. User/Agent creates new Story under Epic
  6. User/Agent creates new Task under new Story
  7. Story and Task are added to Kanban board
  8. Version is determined: RC.EPIC.{NEXT_STORY}.1+1

Postcondition: Story and Task created, linked to Epic, version assigned

3.3 Use Case 3: FR → New Epic​

Actor: User/Agent
Precondition: FR arrives, no matching Story or Epic
Flow:

  1. User/Agent receives FR
  2. User/Agent searches for existing Story
  3. No matching Story found
  4. User/Agent searches for existing Epic
  5. No matching Epic found
  6. User/Agent creates new, conceptually broad Epic
  7. User/Agent creates new Story under new Epic
  8. User/Agent creates new Task under new Story
  9. Epic, Story, and Task are added to Kanban board
  10. Version is determined: RC.{NEXT_EPIC}.1.1+1

Postcondition: Epic, Story, and Task created, version assigned

3.4 Use Case 4: Complex FR → Multiple Tasks​

Actor: User/Agent
Precondition: FR arrives that requires multiple Tasks
Flow:

  1. User/Agent receives FR
  2. User/Agent analyzes FR scope
  3. User/Agent determines FR requires multiple Tasks
  4. User/Agent creates multiple Tasks (under same or different Stories)
  5. Each Task is properly linked and versioned
  6. Tasks are added to appropriate Stories

Postcondition: Multiple Tasks created, properly linked and versioned

3.5 Use Case 5: BR → Bug Fix Task​

Actor: User/Agent
Precondition: BR arrives
Flow:

  1. User/Agent receives BR
  2. User/Agent identifies affected area/component
  3. User/Agent searches for existing Story related to that area
  4. If found: create Task under existing Story
  5. If not found: follow Story/Epic creation flow
  6. Task is marked as bug fix
  7. Version is determined based on Story/Epic

Postcondition: Bug fix Task created, properly linked and versioned

4. Stakeholder Analysis​

4.1 Primary Stakeholders​

AI Agents (Primary Users):

  • Need clear, structured process
  • Need decision trees/flowcharts
  • Need templates for consistency
  • Need examples for learning

Human Users (Secondary Users):

  • Need simple, intuitive process
  • Need clear instructions
  • Need examples
  • Need troubleshooting help

Project Maintainers:

  • Need consistent process
  • Need traceability
  • Need integration with existing systems
  • Need maintainable documentation

4.2 Stakeholder Needs​

AI Agents Need:

  • Structured decision flow
  • Clear criteria for matching
  • Template-based creation
  • Validation rules

Human Users Need:

  • Simple forms/templates
  • Clear instructions
  • Visual guides
  • Quick reference

Project Maintainers Need:

  • Consistent application
  • Full traceability
  • Easy maintenance
  • Framework reusability

5. Gap Analysis​

5.1 Current vs. Required​

ComponentCurrent StateRequired StateGap
FR Template❌ None✅ Structured templateHIGH
BR Template❌ None✅ Structured templateHIGH
Decision Flow❌ Policy only✅ Visual flowchart + criteriaHIGH
Process Guide❌ None✅ Step-by-step guideHIGH
Examples❌ None✅ Worked examplesMEDIUM
Agent Guide❌ None✅ Agent-friendly guideMEDIUM
User Guide❌ None✅ User-friendly guideMEDIUM
Integration Docs❌ Implicit✅ Explicit integration docsLOW

5.2 Priority Gaps​

Critical (Must Have):

  1. FR/BR templates
  2. Decision flow diagram
  3. Step-by-step process guide

Important (Should Have): 4. Worked examples 5. Agent guide 6. User guide

Nice to Have: 7. Automated tooling 8. Integration scripts 9. Validation checks

6. Recommendations​

6.1 Immediate Actions​

  1. Create FR/BR Templates (Task 3)

    • Design structured templates
    • Align with Kanban template structure
    • Include all necessary fields

  2. Design Decision Flow (Task 2)

    • Create visual flowchart
    • Define matching criteria
    • Document edge cases

  3. Document Process (Task 4)

    • Write step-by-step guide
    • Create worked examples
    • Document integrations

6.2 Future Enhancements​

  1. Automation:

    • Intake scripts for common cases
    • Validation checks
    • Integration with issue trackers

  2. Tooling:

    • Interactive decision tree
    • Template generators
    • Validation tools

  3. Analytics:

    • Intake metrics
    • Process efficiency tracking
    • Bottleneck identification

7. Success Criteria​

The intake process will be considered successful when:

  • ✅ FRs/BRs can be converted to Tasks in < 10 minutes (simple cases)
  • ✅ Decision flow is clear and unambiguous
  • ✅ Templates are self-explanatory
  • ✅ Process is documented with examples
  • ✅ Integration with versioning and RW is clear
  • ✅ Both agents and users can follow the process

8. Next Steps​

  1. Task 2: Design FR/BR → Task → Story → Epic decision flow
  2. Task 3: Create FR/BR intake templates and forms
  3. Task 4: Document the intake process with examples
  4. Task 5: Create intake workflow guide for agents/users

9. References​

  • packages/frameworks/kanban/policies/kanban-governance-policy.md (FR/BR rules)
  • docs/project-management/rituals/policy/kanban-governance-policy.md (dev-kit implementation)
  • packages/frameworks/kanban/templates/EPIC_TEMPLATE.md
  • packages/frameworks/kanban/templates/STORY_TEMPLATE.md

End of Analysis Report