Suggest Stories

Name: Suggest Stories
Author: adrianhdezm

adrianhdezm/skills

1 installs
1 repo stars
Updated June 7, 2026
adrianhdezm/skills

suggest-stories is a Claude Code skill that suggests remaining candidate stories for one active epic by comparing epic goals against existing stories and bugfixes, without creating files until accepted.

About

suggest-stories is a Claude Code skill that proposes remaining candidate stories for a single active epic. A developer uses it to plan or revisit the story set, find missing coverage, and pick the next independently implementable slice. It routes defect work to add-bugfix and only writes files when the user accepts a suggestion.

Suggests remaining candidate stories for exactly one active epic
Compares epic goals against existing stories and bugfixes to find gaps
Does not create files until the user accepts a suggestion

Suggest Stories by the numbers

1 all-time installs (skills.sh)
Ranked #2,478 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
Data as of Jul 7, 2026 (Skillselion catalog sync)

At a glance

suggest-stories capabilities & compatibility

Capabilities: story planning · epic decomposition · backlog planning
Use cases: planning · project management
Pricing: Free

From the docs

What suggest-stories says it does

Suggest remaining candidate stories for one active epic by reading the epic plus existing stories and bugfixes, without creating files until the user accepts specific suggestions.

SKILL.md

This skill separates story coverage review from story artifact creation and can be rerun while the epic remains active.

SKILL.md

npx skills add https://github.com/adrianhdezm/skills --skill suggest-stories

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/adrianhdezm/skills/suggest-stories.svg)](https://skillselion.com/skills/adrianhdezm/skills/suggest-stories)

Installs	1
repo stars	★ 1
Last updated	June 7, 2026
Repository	adrianhdezm/skills ↗

What it does

Suggest remaining stories for one active epic by comparing epic goals against existing stories and bugfixes.

Who is it for?

Developers in a spec-driven epic/story workflow planning the next value slice.

Skip if: Projects without the docs/epics/active epic and story file structure.

When should I use this skill?

After validate-epic and any time an epic is active, to plan or revisit its story set.

What you get

A set of independently implementable candidate stories that fill epic coverage gaps is proposed for review.

candidate story suggestions with scope, acceptance criteria themes, dependencies and sequencing

By the numbers

8-item validation checklist
2 helper scripts (list-active-epics.sh, list-epic-child-work.sh)

Files

SKILL.mdMarkdownGitHub ↗

Suggest Stories

Core Rule

Suggest remaining candidate story boundaries for exactly one active epic by comparing the epic goals against existing stories and bugfixes; do not create or modify story files unless the user explicitly accepts one or more suggestions and asks you to proceed with add-story. This skill separates story coverage review from story artifact creation and can be rerun while the epic remains active. Follow references/clarification-policy.md.

Workflow

1. Select exactly one active epic:

If the user provided a specific epic path or slug, use that as the candidate epic.
If the user did not provide a specific epic, run this skill's scripts/list-active-epics.sh <target-repo-root> to list active epics and validation decisions, then choose or ask for exactly one row from that output.
Do not read child stories, bugfixes, code, or broad Product Vision context for multiple epics. Stop and ask the user to choose when more than one epic is plausible and there is no clear single requested epic.
Confirm the selected epic is under docs/epics/active/<epic>/epic.md.

2. Load context from the selected epic:

Read only the selected docs/epics/active/<epic>/epic.md.
Read the source Product Vision when present.
Run this skill's scripts/list-epic-child-work.sh <epic-slug-or-path> <target-repo-root>, then read the existing story_*.md and bugfix_*.md files in the epic that are relevant to coverage, sequencing, gaps, or overlap.
Read relevant docs/knowledge/ concern specs and inspect code, tests, or docs enough to understand current system boundaries.

3. Analyze epic fulfillment:

Map the epic's intent, in-scope items, Product Vision coverage role, risks, rollout, and validation gaps to existing stories and bugfixes.
Identify already-planned work, partial coverage, missing value slices, sequencing constraints, regression boundaries, and duplicated ownership.
Distinguish planned value slices from corrective defect work. Recommend add-bugfix for defects that need root cause and regression preservation.

4. Suggest candidates:

Propose the smallest useful remaining story set that can fulfill the epic's in-scope outcome.
For each candidate, include purpose, user or system value, in-scope and out-of-scope behavior, acceptance criteria themes, regression boundaries, dependencies, sequencing, verification approach, and overlap risk.
Keep each candidate independently implementable and validatable by validate-change-plan.
Do not force a complete story breakdown if the user asked only for the next story or a specific area.

5. Ask for acceptance:

Ask the user which candidate to create, revise, defer, or drop.
If accepted, use add-story for each accepted candidate, one story at a time.
If a candidate is actually a defect fix, recommend add-bugfix instead of creating a story.
If rejected or changed, revise suggestions before writing any artifact.

Validation Checklist

[ ] Exactly one active epic was analyzed.
[ ] Exactly one active epic was selected before child work, code, or broad Product Vision context was loaded.
[ ] Existing stories and bugfixes in the epic were checked for coverage and overlap.
[ ] Suggestions are independently implementable planned value slices, not technical task buckets.
[ ] Defect fixes are routed to add-bugfix.
[ ] Each suggestion maps to specific epic scope, Product Vision items when present, and acceptance criteria themes.
[ ] Gaps, overlap, dependencies, sequencing, regression boundaries, and open questions are explicit.
[ ] No files were created or modified unless the user accepted a suggestion and requested creation.

interface:
  display_name: "Suggest Stories"
  short_description: "Suggest story candidates"
  default_prompt: "Use $suggest-stories to read one active epic and existing child work, identify missing value slices, and suggest story candidates for me to accept before creation."

#!/usr/bin/env bash
#
# Usage:
#   list-active-epics.sh [target-repo-root]
#
# Example output:
#   state	epic_validation_decision	path	title
#   Active	Pass	docs/epics/active/auth/epic.md	Authentication
#   Active	Partial	docs/epics/active/billing/epic.md	Billing
set -euo pipefail

root="${1:-.}"
epic_root="$root/docs/epics/active"

field_value() {
  local file="$1"
  local label="$2"
  sed -n "s/^- ${label}: //p" "$file" | head -n 1
}

section_decision() {
  local file="$1"
  local section="$2"
  awk -v section="$section" '
    $0 == "## " section { in_section = 1; next }
    in_section && /^## / { exit }
    in_section && /^- Decision: / { sub(/^- Decision: /, ""); print; exit }
  ' "$file"
}

title_for() {
  sed -n 's/^# Epic: //p' "$1" | head -n 1
}

printf 'state\tepic_validation_decision\tpath\ttitle\n'

[ -d "$epic_root" ] || exit 0

find "$epic_root" -mindepth 2 -maxdepth 2 -name 'epic.md' 2>/dev/null | sort | while IFS= read -r file; do
  [ -f "$file" ] || continue
  printf '%s\t%s\t%s\t%s\n' "$(field_value "$file" "State")" "$(section_decision "$file" "Epic Validation")" "$file" "$(title_for "$file")"
done

#!/usr/bin/env bash
#
# Usage:
#   list-epic-child-work.sh <epic-slug-or-path> [target-repo-root]
#
# Example output:
#   state	type	path	title
#   Ready	story	docs/epics/active/auth/story_login.md	Add login flow
#   Review	bugfix	docs/epics/active/auth/bugfix_session.md	Fix session expiry
set -euo pipefail

root="."
epic="${1:-}"

if [ -z "$epic" ]; then
  printf 'usage: %s <epic-slug-or-path> [root]\n' "$(basename "$0")" >&2
  exit 2
fi

if [ "$#" -ge 2 ]; then
  root="$2"
fi

case "$epic" in
  */*) epic_dir="$epic" ;;
  *) epic_dir="$root/docs/epics/active/$epic" ;;
esac

if [ ! -d "$epic_dir" ]; then
  printf 'epic directory not found: %s\n' "$epic_dir" >&2
  exit 1
fi

field_value() {
  local file="$1"
  local label="$2"
  sed -n "s/^- ${label}: //p" "$file" | head -n 1
}

title_for() {
  awk '
    /^# Story: / { sub(/^# Story: /, ""); print; exit }
    /^# Bugfix: / { sub(/^# Bugfix: /, ""); print; exit }
  ' "$1"
}

type_for() {
  case "$(basename "$1")" in
    story_*) printf 'story' ;;
    bugfix_*) printf 'bugfix' ;;
    *) printf 'artifact' ;;
  esac
}

printf 'state\ttype\tpath\ttitle\n'

find "$epic_dir" -maxdepth 1 -name 'story_*.md' -o -name 'bugfix_*.md' 2>/dev/null | sort | while IFS= read -r file; do
  [ -f "$file" ] || continue
  printf '%s\t%s\t%s\t%s\n' "$(field_value "$file" "State")" "$(type_for "$file")" "$file" "$(title_for "$file")"
done