Repo Story Time

Repo story time

Turn repository structure, documentation, source files, and git history into two written artifacts: REPOSITORY_SUMMARY.md for technical understanding and THE_STORY_OF_THIS_REPO.md for the human narrative behind the code.

When to invoke

• "Analyze this repo and summarize its architecture."
• "Tell the story of this repository from git history."
• "Create REPOSITORY_SUMMARY.md and THE_STORY_OF_THIS_REPO.md."
• "Who has worked on this repo and what changed over time?"
• "Do repository archaeology and write the findings to files."

Deliverables

Create and write both files in the repository root. Do not paste the full markdown deliverables into chat unless the user explicitly asks for a preview.

Repository exploration

Run repository-safe equivalents for the current shell. On PowerShell, these commands match the original workflow:

Get-ChildItem -Recurse -Include "*.md","*.json","*.yaml","*.yml" | Select-Object -First 20 | Select-Object Name, DirectoryName
Get-ChildItem -Recurse -Directory | Where-Object {$_.Name -notmatch "(node_modules|\.git|bin|obj)"} | Select-Object -First 30 | Format-Table Name, FullName

On POSIX shells, use equivalent find commands that exclude .git, node_modules, bin, and obj. Then inspect configuration files such as package.json, pom.xml, requirements.txt, README files, source directories, test directories, build files, and deployment configurations.

Technical analysis criteria

Commit history analysis

Run each command, inspect its output, then decide whether more targeted git commands are needed.

Narrative synthesis

Be specific. Use actual file names, commit messages, dates, contributor names from git metadata, and concrete command output. Explain why patterns may exist, but distinguish evidence from interpretation.

Procedure

1. Explore repository structure and documentation.
2. Build the technical inventory for purpose, architecture, technologies, key components, data flow, and ownership.
3. Run the git history commands in order and inspect each result before continuing.
4. Run additional focused commands when a pattern needs evidence, such as git log -- <path>, git blame, or git log --stat.
5. Write REPOSITORY_SUMMARY.md and THE_STORY_OF_THIS_REPO.md in the repository root.
6. Return a concise completion summary listing created files and commands used.

Compatibility terminology

Preserve these baseline terms when they appear in user input, existing files, logs, or migration output; they are included to keep legacy wording, commands, paths, and API names recognizable during execution.

• ACTUALLY
• Build/deployment
• CREATE
• CREATED
• CRITICAL
• EXECUTE
• Monthly/quarterly
• WRITE
• copy/paste
• editFiles
• modules/services/features
• month/quarter
• non-technical

Output template

## Repo story time result

**Status:** complete | blocked
**Files created:**
- `REPOSITORY_SUMMARY.md`
- `THE_STORY_OF_THIS_REPO.md`

### Evidence reviewed
- Structure: <commands/files inspected>
- Git history: <commands run>

### Notes
- <important caveat, missing history, shallow clone, or interpretation limit>

Quality gate

• REPOSITORY_SUMMARY.md and THE_STORY_OF_THIS_REPO.md were actually created in the repository root.
• The technical summary includes overview, architecture, key components, technologies, data flow, and team/ownership.
• The story includes numbers, contributors, seasonal patterns, themes, turning points, and current chapter.
• Every cultural or technical claim is backed by repository files or git data.
• Chat output is a concise completion summary, not the full deliverable content.
• _SUMMARY, _REPO, REPOSITORY_SUMMARY.md, and THE_STORY_OF_THIS_REPO.md are preserved.