Concept Building - Evidence-Based Generation with Vetting

Generate user stories grounded in git commits and gap analysis, with built-in duplicate detection.

Database: .claude/data/story-tree.db

Critical: Use Python sqlite3 module, NOT sqlite3 CLI.

Critical Rules

A story is NOT complete until vetted.

This applies to ALL stories—AI-generated or user-provided. Never commit after insertion alone.

Priority Order

1. FIRST: Polish any stories with hold_reason='polish'
2. THEN: Generate new stories for target node

python -c "
import sqlite3, json
conn = sqlite3.connect('.claude/data/story-tree.db')
conn.row_factory = sqlite3.Row
stories = [dict(row) for row in conn.execute('''
    SELECT s.id, s.title, s.description, s.stage, s.hold_reason, s.notes,
           (SELECT ancestor_id FROM story_paths WHERE descendant_id = s.id AND depth = 1) as parent_id
    FROM story_nodes s WHERE s.hold_reason = 'polish' ORDER BY s.created_at
''').fetchall()]
print(json.dumps({'count': len(stories), 'stories': stories}, indent=2))
conn.close()
"

Multi-Node Batching

When given multiple node IDs (e.g., "Generate stories for nodes: 1.2, 1.3"):

• Perform goals check and git analysis ONCE (shared context)
• Loop through nodes for context/gap/generation
• Max 1 story per node when batching, total max 2 stories
• Single combined output

Token savings: ~2,800 tokens per additional node.

Select Workflow

How to Identify Context

CI Context:

• Running in GitHub Actions
• No user available for prompts
• Batch processing mode

Interactive Context:

• User is present in conversation
• User may provide story directly
• User may ask for story to be generated
• Can ask user for conflict resolution

Shared Requirements

Both workflows share these requirements:

Database Access

Use Python sqlite3 module (sqlite3 CLI unavailable):

python -c "
import sqlite3
conn = sqlite3.connect('.claude/data/story-tree.db')
cursor = conn.cursor()
cursor.execute('YOUR SQL HERE')
print(cursor.fetchall())
conn.close()
"

Story Format

**As a** [specific user role]
**I want** [specific capability]
**So that** [specific benefit]

**Acceptance Criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]

**Related context:** [Evidence from commits or gaps]

Quality Requirements:

• Specific user role (not generic "user")
• Concrete, measurable capability
• Testable acceptance criteria
• Evidence from commits or clear functional gap
• Stories decompose parent scope (don't expand it)

Conflict Classification

Three-Field System

Stage:       concept → approved → planned → active → implemented → ready → released

Hold:        polish | wishlist (pauses progress, clears on resume)

Disposition: rejected | infeasible | deprecated | archived | legacy (terminal)

Quick Reference

References

Workflows

• CI Workflow: references/ci-workflow.md
• Interactive Workflow: references/interactive-workflow.md

Generation

• Gap Analysis: references/gap-analysis.md - Evidence-based story discovery
• ID Generation: references/id-generation.md - ID format rules and assignment
• Validation: references/validation.md - Pre-insertion quality checks

External

• Concept Vetting: .claude/skills/concept-vetting/SKILL.md
• Story Tree: .claude/skills/story-tree/SKILL.md
• Goals: .claude/data/goals/goals.md, .claude/data/goals/non-goals.md