investigating-codebase-for-user-stories

name	investigating-codebase-for-user-stories
description	Use when asked to create user stories from a codebase, document existing features as stories, or reverse-engineer requirements from code

Investigating Codebase for User Stories

Overview

Systematic codebase investigation to produce well-formed user stories with acceptance criteria and traceability. Prevents shallow exploration that misses features or produces untestable stories.

When to Use

• Asked to "create user stories from this codebase"
• Need to document existing features as stories
• Reverse-engineering requirements from implementation
• Onboarding to understand what a system does

Investigation Phases

digraph investigation {
    rankdir=TB;
    node [shape=box];

    identify [label="1. Identify User Types\n(routes, auth, controllers)"];
    map [label="2. Map Feature Areas\n(by controller/domain)"];
    trace [label="3. Trace User Journeys\n(entry points → outcomes)"];
    write [label="4. Write Stories\nwith Acceptance Criteria"];
    validate [label="5. Validate Coverage\n(cross-check routes/views)"];
    deps [label="6. Map Dependencies\n(blocks/blocked-by)"];
    save [label="7. Save to Files\n(docs/user-stories/)"];

    identify -> map -> trace -> write -> validate -> deps -> save;
}

Phase 1: Identify User Types

Investigate authentication and authorization to find distinct user types:

Look In	What to Find
Middleware	Auth guards, role checks, permission gates
Routes	Route groups with different middleware
User model	Roles, groups, subscription tiers
Views/layouts	Different dashboards, nav menus

Output: List of user types (e.g., Guest, Registered User, Admin, Subscriber)

Phase 2: Map Feature Areas

Group functionality by domain, not by file structure:

Feature Area          | Controllers/Services        | User Types
---------------------|-----------------------------|-----------
Authentication       | AuthController, MfaController| All
Product Catalog      | ProductController, SearchController| Registered+
Notifications        | NotificationController      | Subscriber+
Admin Management     | AdminController             | Admin

Key locations to scan:

• routes/web.php, routes/api.php - all endpoints
• app/Http/Controllers/ - feature groupings
• resources/views/ - UI capabilities
• Database migrations - data model capabilities

Phase 3: Trace User Journeys

For each feature area, trace complete user journeys:

1. Entry point - How does user reach this feature?
2. Actions available - What can they do?
3. State changes - What data changes?
4. Outcomes - What feedback/result do they see?

Document with code references: NotificationController:45 for traceability.

Phase 4: Write Stories with Acceptance Criteria

Story Format

**As a** [specific user type from Phase 1],
**I want** [action/capability traced in Phase 3],
**so that** [business value/outcome].

**Acceptance Criteria:**
- [ ] Given [precondition], when [action], then [outcome]
- [ ] Given [alternate precondition], when [action], then [different outcome]
- [ ] Edge case: [boundary condition handling]

**Code References:** ControllerName:line, ViewName.blade.php
**Complexity:** S/M/L (based on code paths and integrations)

Sizing Heuristics

Size	Indicators
S	Single controller method, no external integrations
M	Multiple methods, 1-2 integrations, some branching
L	Cross-cutting, multiple services, complex state

Phase 5: Validate Coverage

Cross-check stories against:

• All routes have corresponding stories
• All views have corresponding stories
• All user types have stories
• No orphan features (code without stories)

Phase 6: Map Dependencies

Identify which stories depend on others:

Story A (Auth) ─────► Story B (Notifications)
                     "User must be authenticated"

Story C (Admin) ────► Story D (User Management)
                     "Admin role required"

Dependency types:

• Blocks: Story must complete before another can start
• Relates to: Stories share code/features but are independent
• Duplicates: Overlapping functionality (merge or clarify scope)

Add to each story file:

## Dependencies
- **Blocked by:** [guest-signup](../authentication/guest-signup.md)
- **Blocks:** [subscriber-export-data](../account/subscriber-export-data.md)

Phase 7: Save to Files

1. Create directory structure: mkdir -p docs/user-stories/{feature-areas}
2. Write each story to its own file using naming convention
3. Generate README.md index with coverage matrix and links
4. Include dependency graph in README

Output Structure

Save stories as separate markdown files in docs/user-stories/:

docs/user-stories/
├── README.md                    # Index with coverage matrix
├── authentication/
│   ├── guest-signup.md
│   ├── guest-login.md
│   └── user-logout.md
├── notifications/
│   ├── user-create-notification.md
│   └── user-manage-notifications.md
└── admin/
    └── admin-manage-users.md

File Naming Convention

{user-type}-{action-verb}-{feature}.md

Examples:

• guest-complete-eligibility.md
• subscriber-configure-notifications.md
• admin-reset-user-password.md

Individual Story File Template

# {Story Title}

**As a** {user type},
**I want** {capability},
**so that** {benefit}.

## Acceptance Criteria

- [ ] Given {precondition}, when {action}, then {outcome}
- [ ] Given {alternate}, when {action}, then {different outcome}
- [ ] Edge case: {boundary condition}

## Dependencies

- **Blocked by:** [story-name](../feature/story-name.md)
- **Blocks:** [other-story](../feature/other-story.md)
- **Relates to:** [related-story](../feature/related-story.md)

## Code References

| Component | Location |
|-----------|----------|
| Controller | `AppController:45` |
| View | `feature.blade.php` |
| Model | `Feature.php` |

## Complexity

**Size:** S/M/L

**Rationale:** {why this size}

README.md (Index File)

# User Stories: {Project Name}

Generated: {date}

## Coverage Matrix

| Feature Area | Guest | User | Admin | Stories | Routes |
|--------------|-------|------|-------|---------|--------|
| Auth         | 3     | 2    | 1     | 6       | 8/8    |

## Dependency Graph

```mermaid
graph LR
    A[guest-signup] --> B[user-create-notification]
    A --> C[user-view-products]
    B --> D[subscriber-export-data]
    C --> D

Stories by Feature Area

Authentication

• Guest Signup
• Guest Login

Notifications

• Create Notification

## GitHub Issue Output

Generate stories as GitHub issues for sprint planning:

### Single Issue Creation

```bash
gh issue create \
  --title "As a guest, I want to sign up" \
  --body "$(cat docs/user-stories/authentication/guest-signup.md)" \
  --label "user-story,feature-area:auth,size:M"

Batch Issue Creation Script

Generate create-issues.sh alongside stories:

#!/bin/bash
# Auto-generated from user stories

gh issue create --title "Guest Signup" \
  --body-file docs/user-stories/authentication/guest-signup.md \
  --label "user-story,auth,size:S"

gh issue create --title "User Create Notification" \
  --body-file docs/user-stories/notifications/user-create-notification.md \
  --label "user-story,notifications,size:M" \
  --milestone "Sprint 2"

Recommended Labels

Create these labels in your repo:

Label	Description
user-story	All user stories
size:S / size:M / size:L	Complexity
blocked	Has unresolved dependencies
feature-area:{name}	Feature grouping

Common Mistakes

Mistake	Fix
Listing code features, not user capabilities	Start from user types, not controllers
Missing acceptance criteria	Every story needs Given/When/Then
No traceability	Include file:line references
Flat list without grouping	Group by feature area → user type
Assumed user types	Verify from auth/middleware code
Missing edge cases	Check error handlers, validation rules
All stories in one file	Separate file per story in docs/user-stories/
No index/README	Always generate README.md with coverage matrix
Missing dependencies	Trace auth/middleware chains for implicit blocks
Circular dependencies	Indicates stories need to be split or merged
No GitHub labels	Create labels before running batch issue script