Skip to content

Commit bfbbd19

Browse files
committed
feat: enhance error handling and improve narrative structure in repo story command
1 parent 6df632b commit bfbbd19

1 file changed

Lines changed: 10 additions & 0 deletions

File tree

templates/commands/repo-story.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ Run `{SCRIPT}` to produce `history.json` and parse the JSON output for these top
6969

7070
**Error Handling**:
7171
If the script fails:
72+
7273
- **Git not available**: Inform user that a Git repository is required
7374
- **No commits found**: Report that the repository has no history to analyze
7475
- **Python missing (bash only)**: Suggest running the PowerShell variant or installing Python 3
@@ -91,6 +92,7 @@ Construct the repo story using the following structure. Every claim **MUST** cit
9192
#### A. Executive Summary (Business Audience)
9293

9394
Write 3–5 paragraphs covering:
95+
9496
- **What this project is** — purpose derived from repo name, README presence, and language mix
9597
- **Scale and maturity** — total commits, contributor count, age of first commit, latest activity
9698
- **Velocity trend** — month-over-month commit patterns from `timeline`, acceleration or deceleration
@@ -104,34 +106,40 @@ Use plain language. Avoid jargon. Target a VP/director reading level.
104106
For each of the following subsections, provide evidence-backed analysis:
105107

106108
##### Development Velocity
109+
107110
- Commits per month trend (cite `timeline` data)
108111
- Lines added vs removed (cite `volume_metrics`)
109112
- Churn ratio interpretation — high churn = refactoring, low churn = greenfield
110113
- If `--compare-baseline` provided, show delta between baseline and current period
111114

112115
##### Contributor Dynamics
116+
113117
- Role distribution from `contributor_census` (use anonymized roles, not real names)
114118
- Bus factor assessment — what percentage of commits come from top contributor?
115119
- Team growth or contraction over the timeline
116120

117121
##### Quality Signals
122+
118123
- Test-to-source file ratio (cite `test_metrics`)
119124
- Conventional commit adoption rate (cite `commit_message_metrics.conventional_percentage`)
120125
- Commit message quality — average length, prefix diversity
121126

122127
##### Governance & Process Maturity
128+
123129
- Merge commit percentage as PR workflow proxy (cite `governance_maturity`)
124130
- Tag discipline — regular releases vs sporadic
125131
- Branch strategy signals from merge patterns
126132

127133
##### Architecture & Technology
134+
128135
- Language/framework indicators from `technical_signals`
129136
- Configuration maturity — CI, linting, formatting, dependency management
130137
- Hotspot analysis — most-modified files may indicate active development or instability
131138

132139
#### C. Change Pattern Analysis
133140

134141
Using `change_patterns`:
142+
135143
- Identify the top 5 most-modified files and explain what they suggest
136144
- Flag any files with disproportionate churn as potential refactoring candidates or complexity hotspots
137145
- Note directory-level patterns (e.g., "80% of changes in src/ — active development area")
@@ -151,6 +159,7 @@ Connect milestones to surrounding commit activity — did velocity spike before
151159
#### E. Constitution Alignment (Optional)
152160

153161
If `/.documentation/memory/constitution.md` exists:
162+
154163
- Read the constitution principles
155164
- Map governance metrics to relevant principles
156165
- Note areas of strong alignment and gaps
@@ -203,6 +212,7 @@ Use this document structure:
203212
### 5. Summary
204213

205214
After saving, present:
215+
206216
1. The **Executive Summary** section directly in chat for immediate reading
207217
2. The full file path where the complete narrative was saved
208218
3. One-line takeaways:

0 commit comments

Comments
 (0)