investigating-codebase-for-user-stories

Name: investigating-codebase-for-user-stories
Author: aaddrick

120stars16forks

How to install investigating-codebase-for-user-stories?

aaddrick/claude-pipeline/investigating-codebase-for-user-stories

$npx -y skills add aaddrick/claude-pipeline --skill investigating-codebase-for-user-stories

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Investigating Codebase for User Stories
2
3	## Overview
4
5	Systematic codebase investigation to produce well-formed user stories with acceptance criteria and traceability. Prevents shallow exploration that misses features or produces untestable stories.
6
7	## When to Use
8
9	- Asked to "create user stories from this codebase"
10	- Need to document existing features as stories
11	- Reverse-engineering requirements from implementation
12	- Onboarding to understand what a system does
13
14	## Investigation Phases
15
16	```dot
17	digraph investigation {
18	rankdir=TB;
19	node [shape=box];
20
21	identify [label="1. Identify User Types\n(routes, auth, controllers)"];
22	map [label="2. Map Feature Areas\n(by controller/domain)"];
23	trace [label="3. Trace User Journeys\n(entry points → outcomes)"];
24	write [label="4. Write Stories\nwith Acceptance Criteria"];
25	validate [label="5. Validate Coverage\n(cross-check routes/views)"];
26	deps [label="6. Map Dependencies\n(blocks/blocked-by)"];
27	save [label="7. Save to Files\n(docs/user-stories/)"];
28
29	identify -> map -> trace -> write -> validate -> deps -> save;
30	}
31	```
32
33	## Phase 1: Identify User Types
34
35	Investigate authentication and authorization to find distinct user types:
36
37	\| Look In \| What to Find \|
38	\|---------\|--------------\|
39	\| Middleware \| Auth guards, role checks, permission gates \|
40	\| Routes \| Route groups with different middleware \|
41	\| User model \| Roles, groups, subscription tiers \|
42	\| Views/layouts \| Different dashboards, nav menus \|
43
44	Output: List of user types (e.g., Guest, Registered User, Admin, Subscriber)
45
46	## Phase 2: Map Feature Areas
47
48	Group functionality by domain, not by file structure:
49
50	```
51	Feature Area \| Controllers/Services \| User Types
52	---------------------\|-----------------------------\|-----------
53	Authentication \| AuthController, MfaController\| All
54	Product Catalog \| ProductController, SearchController\| Registered+
55	Notifications \| NotificationController \| Subscriber+
56	Admin Management \| AdminController \| Admin
57	```
58
59	Key locations to scan:
60	- `routes/web.php`, `routes/api.php` - all endpoints
61	- `app/Http/Controllers/` - feature groupings
62	- `resources/views/` - UI capabilities
63	- Database migrations - data model capabilities
64
65	## Phase 3: Trace User Journeys
66
67	For each feature area, trace complete user journeys:
68
69	1. Entry point - How does user reach this feature?
70	2. Actions available - What can they do?
71	3. State changes - What data changes?
72	4. Outcomes - What feedback/result do they see?
73
74	Document with code references: `NotificationController:45` for traceability.
75
76	## Phase 4: Write Stories with Acceptance Criteria
77
78	### Story Format
79
80	```
81	As a [specific user type from Phase 1],
82	I want [action/capability traced in Phase 3],
83	so that [business value/outcome].
84
85	Acceptance Criteria:
86	- [ ] Given [precondition], when [action], then [outcome]
87	- [ ] Given [alternate precondition], when [action], then [different outcome]
88	- [ ] Edge case: [boundary condition handling]
89
90	Code References: ControllerName:line, ViewName.blade.php
91	Complexity: S/M/L (based on code paths and integrations)
92	```
93
94	### Sizing Heuristics
95
96	\| Size \| Indicators \|
97	\|------\|------------\|
98	\| S \| Single controller method, no external integrations \|
99	\| M \| Multiple methods, 1-2 integrations, some branching \|
100	\| L \| Cross-cutting, multiple services, complex state \|
101
102	## Phase 5: Validate Coverage
103
104	Cross-check stories against:
105	- [ ] All routes have corresponding stories
106	- [ ] All views have corresponding stories
107	- [ ] All user types have stories
108	- [ ] No orphan features (code without stories)
109
110	## Phase 6: Map Dependencies
111
112	Identify which stories depend on others:
113
114	```
115	Story A (Auth) ─────► Story B (Notifications)
116	"User must be authenticated"
117
118	Story C (Admin) ────► Story D (User Management)
119	"Admin role required"
120	```
121
122	Dependency types:
123	- Blocks: Story must complete before another can start
124	- Relates to: Stories share code/features but are independent
125	- Duplicates: Overlapping functionality (merge or clarify scope)
126
127	Add to each story file:
128	```markdown
129	## Dependencies
130	- Blocked by: [guest-signup](../authentication/guest-signup.md)
131	- Blocks: [subscriber-export-data](../account/subscriber-export-data.md)
132	```
133
134	## Phase 7: Save to Files
135
136	1. Create directory structure: `mkdir -p docs/user-stories/{feature-areas}`
137	2. Write each story to its own file using naming convention
138	3. Generate `README.md` index with coverage matrix and links
139	4. Include dependency graph in README
140
141	## Output Structure
142
143	Save stories as separate markdown files in `docs/user-stories/`:
144
145	```
146	docs/user-stories/
147	├── README.md # Index with coverage matrix
148	├── authentication/
149	│ ├── guest-sig

People who liked this also viewed

6 picks

Type

investigating-codebase-for-user-stories

120stars16forks

View on GitHub

How to install investigating-codebase-for-user-stories?

aaddrick/claude-pipeline/investigating-codebase-for-user-stories

$npx -y skills add aaddrick/claude-pipeline --skill investigating-codebase-for-user-stories

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Investigating Codebase for User Stories
2
3	## Overview
4
5	Systematic codebase investigation to produce well-formed user stories with acceptance criteria and traceability. Prevents shallow exploration that misses features or produces untestable stories.
6
7	## When to Use
8
9	- Asked to "create user stories from this codebase"
10	- Need to document existing features as stories
11	- Reverse-engineering requirements from implementation
12	- Onboarding to understand what a system does
13
14	## Investigation Phases
15
16	```dot
17	digraph investigation {
18	rankdir=TB;
19	node [shape=box];
20
21	identify [label="1. Identify User Types\n(routes, auth, controllers)"];
22	map [label="2. Map Feature Areas\n(by controller/domain)"];
23	trace [label="3. Trace User Journeys\n(entry points → outcomes)"];
24	write [label="4. Write Stories\nwith Acceptance Criteria"];
25	validate [label="5. Validate Coverage\n(cross-check routes/views)"];
26	deps [label="6. Map Dependencies\n(blocks/blocked-by)"];
27	save [label="7. Save to Files\n(docs/user-stories/)"];
28
29	identify -> map -> trace -> write -> validate -> deps -> save;
30	}
31	```
32
33	## Phase 1: Identify User Types
34
35	Investigate authentication and authorization to find distinct user types:
36
37	\| Look In \| What to Find \|
38	\|---------\|--------------\|
39	\| Middleware \| Auth guards, role checks, permission gates \|
40	\| Routes \| Route groups with different middleware \|
41	\| User model \| Roles, groups, subscription tiers \|
42	\| Views/layouts \| Different dashboards, nav menus \|
43
44	Output: List of user types (e.g., Guest, Registered User, Admin, Subscriber)
45
46	## Phase 2: Map Feature Areas
47
48	Group functionality by domain, not by file structure:
49
50	```
51	Feature Area \| Controllers/Services \| User Types
52	---------------------\|-----------------------------\|-----------
53	Authentication \| AuthController, MfaController\| All
54	Product Catalog \| ProductController, SearchController\| Registered+
55	Notifications \| NotificationController \| Subscriber+
56	Admin Management \| AdminController \| Admin
57	```
58
59	Key locations to scan:
60	- `routes/web.php`, `routes/api.php` - all endpoints
61	- `app/Http/Controllers/` - feature groupings
62	- `resources/views/` - UI capabilities
63	- Database migrations - data model capabilities
64
65	## Phase 3: Trace User Journeys
66
67	For each feature area, trace complete user journeys:
68
69	1. Entry point - How does user reach this feature?
70	2. Actions available - What can they do?
71	3. State changes - What data changes?
72	4. Outcomes - What feedback/result do they see?
73
74	Document with code references: `NotificationController:45` for traceability.
75
76	## Phase 4: Write Stories with Acceptance Criteria
77
78	### Story Format
79
80	```
81	As a [specific user type from Phase 1],
82	I want [action/capability traced in Phase 3],
83	so that [business value/outcome].
84
85	Acceptance Criteria:
86	- [ ] Given [precondition], when [action], then [outcome]
87	- [ ] Given [alternate precondition], when [action], then [different outcome]
88	- [ ] Edge case: [boundary condition handling]
89
90	Code References: ControllerName:line, ViewName.blade.php
91	Complexity: S/M/L (based on code paths and integrations)
92	```
93
94	### Sizing Heuristics
95
96	\| Size \| Indicators \|
97	\|------\|------------\|
98	\| S \| Single controller method, no external integrations \|
99	\| M \| Multiple methods, 1-2 integrations, some branching \|
100	\| L \| Cross-cutting, multiple services, complex state \|
101
102	## Phase 5: Validate Coverage
103
104	Cross-check stories against:
105	- [ ] All routes have corresponding stories
106	- [ ] All views have corresponding stories
107	- [ ] All user types have stories
108	- [ ] No orphan features (code without stories)
109
110	## Phase 6: Map Dependencies
111
112	Identify which stories depend on others:
113
114	```
115	Story A (Auth) ─────► Story B (Notifications)
116	"User must be authenticated"
117
118	Story C (Admin) ────► Story D (User Management)
119	"Admin role required"
120	```
121
122	Dependency types:
123	- Blocks: Story must complete before another can start
124	- Relates to: Stories share code/features but are independent
125	- Duplicates: Overlapping functionality (merge or clarify scope)
126
127	Add to each story file:
128	```markdown
129	## Dependencies
130	- Blocked by: [guest-signup](../authentication/guest-signup.md)
131	- Blocks: [subscriber-export-data](../account/subscriber-export-data.md)
132	```
133
134	## Phase 7: Save to Files
135
136	1. Create directory structure: `mkdir -p docs/user-stories/{feature-areas}`
137	2. Write each story to its own file using naming convention
138	3. Generate `README.md` index with coverage matrix and links
139	4. Include dependency graph in README
140
141	## Output Structure
142
143	Save stories as separate markdown files in `docs/user-stories/`:
144
145	```
146	docs/user-stories/
147	├── README.md # Index with coverage matrix
148	├── authentication/
149	│ ├── guest-sig

People who liked this also viewed

6 picks

Type