Agent skill

Investigating Codebase For User Stories

by aaddrick in aaddrick/claude-pipeline

A skill your agent uses when asked to create user stories from a codebase, document existing features as stories, or reverse-engineer requirements from code

MITAuto-check passedProduct & Project Management

Install Investigating Codebase For User Stories

skills CLI
$ npx skills add aaddrick/claude-pipeline --skill investigating-codebase-for-user-stories -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install aaddrick/claude-pipeline investigating-codebase-for-user-stories --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/aaddrick/claude-pipeline.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/investigating-codebase-for-user-stories .claude/skills/investigating-codebase-for-user-stories && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
investigating-codebase-for-user-stories
GitHub stars
130
Token cost
~2.2k tokens
SKILL.md length
504 words
Files
1
Skills in repo
12
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses when asked to create user stories from a codebase, document existing features as stories, or reverse-engineer requirements from code

  • Works in 7 steps: Identify User Types → Map Feature Areas → Trace User Journeys → …
  • Asked to create user stories from a codebase
  • SKILL.md covers Overview, When to Use, Investigation Phases and Phase 1: Identify User Types, plus 9 more sections
  • Calls gh

What it does

Investigating Codebase For User Stories is an agent skill from aaddrick/claude-pipeline. Use when asked to create user stories from a codebase, document existing features as stories, or reverse-engineer requirements from code

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Product & Project Management, covering User stories. The repository describes itself as: Portable Claude Code multi-agent pipeline - skills, agents, hooks, orchestration scripts, and quality gates. The licence is MIT.

When your agent uses it

  • Asked to create user stories from a codebase
  • Document existing features as stories
  • Reverse-engineer requirements from code

Example prompts

  • “/investigating-codebase-for-user-stories”

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Identify User Types
  2. Map Feature Areas
  3. Trace User Journeys
  4. Write Stories with Acceptance Criteria
  5. Validate Coverage
  6. Map Dependencies
  7. Save to Files

What it can do on your machine

Read from SKILL.md and the folder at commit 402eac7. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • gh

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use gh, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Investigating Codebase For User Stories loads about 2.2k tokens when it runs. Until then it costs about 44 tokens; SKILL.md has 504 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~44
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from aaddrick/claude-pipeline at commit 402eac7, republished under its MIT licence (© aaddrick). 504 words, ~2,179 tokens.

Download SKILL.mdSave it as .claude/skills/investigating-codebase-for-user-stories/SKILL.md (or your agent's skills folder).
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

dot
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 InWhat to Find
MiddlewareAuth guards, role checks, permission gates
RoutesRoute groups with different middleware
User modelRoles, groups, subscription tiers
Views/layoutsDifferent 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
SizeIndicators
SSingle controller method, no external integrations
MMultiple methods, 1-2 integrations, some branching
LCross-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:

markdown
## Dependencies
- **Blocked by:** [guest-signup](../authentication/guest-signup.md)
- **Blocks:** [subscriber-export-data](../account/subscriber-export-data.md)
Show full SKILL.md (208 more words)Show less

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
markdown
# {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)
markdown
# 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
Notifications

## 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:

bash
#!/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"

Create these labels in your repo:

LabelDescription
user-storyAll user stories
size:S / size:M / size:LComplexity
blockedHas unresolved dependencies
feature-area:{name}Feature grouping

Common Mistakes

MistakeFix
Listing code features, not user capabilitiesStart from user types, not controllers
Missing acceptance criteriaEvery story needs Given/When/Then
No traceabilityInclude file:line references
Flat list without groupingGroup by feature area → user type
Assumed user typesVerify from auth/middleware code
Missing edge casesCheck error handlers, validation rules
All stories in one fileSeparate file per story in docs/user-stories/
No index/READMEAlways generate README.md with coverage matrix
Missing dependenciesTrace auth/middleware chains for implicit blocks
Circular dependenciesIndicates stories need to be split or merged
No GitHub labelsCreate labels before running batch issue script

© aaddrick, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/investigating-codebase-for-user-stories of aaddrick/claude-pipeline.

Open the folder on GitHubat commit 402eac7

Compare with similar skills

Investigating Codebase For User Stories next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Investigating Codebase For User Stories compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Investigating Codebase For User Stories this skillaaddrick/claude-pipeline130—~2.2kAutomated safety check: PassMIT
User Story Writerdeanpeters/Product-Manager-Skills7.2k2 repos~2.9kAutomated safety check: PassCustom licence
Ralph Tui Create Beadssubsy/ralph-tui2.5k1 repos~2.6kAutomated safety check: PassMIT
Agile Product Owneralirezarezvani/claude-skills28k3 repos~3.2kAutomated safety check: PassMIT
Ralph Tui Create Beads Rustsubsy/ralph-tui2.5k1 repos~2.8kAutomated safety check: PassMIT
To Specbestofjs/bestofjs3.1k21 repos~757Automated safety check: PassMIT

Similar skills

  • User Story Writer

    deanpeters/Product-Manager-Skills

    Writes user stories in Mike Cohn's format with Gherkin acceptance criteria, turning user needs into development-ready work with testable conditions.

    7.2k GitHub starsUsed in 2 repos~2.9k tokens
    Product & Project ManagementAuto-check passed
  • Ralph Tui Create Beads

    subsy/ralph-tui

    Convert PRDs to beads for ralph-tui execution. An agent skill from subsy/ralph-tui.

    2.5k GitHub starsUsed in 1 repo~2.6k tokens
    Product & Project ManagementAuto-check passed
  • Agile Product Owner

    alirezarezvani/claude-skills

    Writes INVEST-checked user stories with acceptance criteria, splits epics, plans sprints from velocity and ranks the backlog with a weighted score.

    28k GitHub starsUsed in 3 repos~3.2k tokens
    Product & Project ManagementAuto-check passed
  • Convert PRDs to beads for ralph-tui execution using beads-rust (br CLI).

    2.5k GitHub starsUsed in 1 repo~2.8k tokens
    Product & Project ManagementAuto-check passed
  • To Spec

    bestofjs/bestofjs

    Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.

    3.1k GitHub starsUsed in 21 repos~757 tokens
    Product & Project ManagementAuto-check passed
  • Ralph Tui Create JSON

    subsy/ralph-tui

    Convert PRDs to prd.json format for ralph-tui execution. An agent skill from subsy/ralph-tui.

    2.5k GitHub starsUsed in 1 repo~2.6k tokens
    Product & Project ManagementAuto-check passed

More from aaddrick/claude-pipeline

All 12 skills in this repo
  • Writing Agents

    aaddrick/claude-pipeline

    A skill your agent uses when creating new agents, editing existing agents, or defining specialized subagent roles for the Task tool

    130 GitHub starsUsed in 1 repo~3.3k tokens
    Auto-check passed
  • Adapting Claude Pipeline

    aaddrick/claude-pipeline

    A skill your agent uses when adapting the generic .claude pipeline folder to a specific codebase - adjusting skills, agents, hooks, scripts, prompts, and settings for the target project's tech stack…

    130 GitHub stars~2.8k tokensUpdated 7 mo ago
    Auto-check passed
  • Review UI

    aaddrick/claude-pipeline

    Comprehensive UI/CSS review using parallel agents. An agent skill from aaddrick/claude-pipeline.

    130 GitHub stars~2.5k tokensUpdated 7 mo ago
    Auto-check passed
  • Using Git Worktrees

    aaddrick/claude-pipeline

    A skill your agent uses when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees in .worktrees/

    130 GitHub stars~1.3k tokensUpdated 7 mo ago
    Auto-check passed
  • Implement Issue

    aaddrick/claude-pipeline

    A skill your agent uses when given a GitHub issue number and base branch to implement end-to-end

    130 GitHub starsUsed in 1 repo~889 tokens
    Auto-check passed
  • Write Docblocks

    aaddrick/claude-pipeline

    A skill your agent uses when documentation coverage is low, after composer docs:coverage shows gaps, or when asked to batch-write PHPDoc blocks across multiple files

    130 GitHub stars~956 tokensUpdated 7 mo ago
    Auto-check passed

Questions about Investigating Codebase For User Stories

What does Investigating Codebase For User Stories do?

A skill your agent uses 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 is an agent skill from aaddrick/claude-pipeline.

When should I use Investigating Codebase For User Stories?

Investigating Codebase For User Stories fits situations like: asked to create user stories from a codebase; document existing features as stories; reverse-engineer requirements from code.

How do I install Investigating Codebase For User Stories in Claude Code?

Run `npx skills add aaddrick/claude-pipeline --skill investigating-codebase-for-user-stories -a claude-code`. Or copy the skill folder (.claude/skills/investigating-codebase-for-user-stories in aaddrick/claude-pipeline) into .claude/skills/investigating-codebase-for-user-stories in your project. Claude Code loads it when a task matches its description.

How do I install Investigating Codebase For User Stories in Codex?

Run `npx skills add aaddrick/claude-pipeline --skill investigating-codebase-for-user-stories -a codex`. Or copy the skill folder (.claude/skills/investigating-codebase-for-user-stories in aaddrick/claude-pipeline) into .agents/skills/investigating-codebase-for-user-stories in your project. Codex loads it when a task matches its description.

Can I use Investigating Codebase For User Stories in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add aaddrick/claude-pipeline --skill investigating-codebase-for-user-stories -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/investigating-codebase-for-user-stories, .gemini/skills/investigating-codebase-for-user-stories, .github/skills/investigating-codebase-for-user-stories and .opencode/skills/investigating-codebase-for-user-stories in your project.

What does Investigating Codebase For User Stories need to run?

Going by SKILL.md and its folder, Investigating Codebase For User Stories needs the command-line tools its instructions call (gh).

Does Investigating Codebase For User Stories access the network?

SKILL.md contains no URLs. Its commands use gh, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Investigating Codebase For User Stories safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Investigating Codebase For User Stories use?

Investigating Codebase For User Stories is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Investigating Codebase For User Stories use?

About 2.2k tokens (SKILL.md is roughly 8.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Investigating Codebase For User Stories?

Skills that share tags, products or a category with Investigating Codebase For User Stories: User Story Writer (deanpeters/Product-Manager-Skills, 7.2k stars), Ralph Tui Create Beads (subsy/ralph-tui, 2.5k stars), Agile Product Owner (alirezarezvani/claude-skills, 28k stars) and Ralph Tui Create Beads Rust (subsy/ralph-tui, 2.5k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Investigating Codebase For User Stories?

aaddrick (a GitHub user) maintains it in aaddrick/claude-pipeline, which has 130 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on February 25, 2026.

Source: aaddrick/claude-pipeline on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.