Repository Overview Generator

Failure modes it recognizes

• A directory-tree summary labels folders without explaining the runtime flow, leaving a newcomer unable to trace real behavior.
• Architecture claims inferred from naming conflict with the executable entry point or deployment configuration that governs production.
• Dependency documentation reports broad major versions from manifests while the lock file or resolved build uses a materially different version.
• A component map lists namespaces or files but omits the contracts and data dependencies through which components interact.
• An API table copies route names without tracing authentication, request validation, side effects, error contracts, or downstream integrations.
• Setup instructions repeat stale documentation without running repository-defined commands, so the first contributor experience fails immediately.
• Generated artifacts are described as source-of-truth code, causing later agents to edit output that will be overwritten by the next build.
• A team playbook quotes one reviewer preference as policy without checking the final resolution, recurrence, area scope, or current owner.
• The overview copies credentials, customer data, or local environment values into a durable document while trying to be comprehensive.

Answers it will reject

• Listing every file with one sentence each; exhaustive inventory consumes attention without teaching boundaries or change paths.
• Calling a pattern architectural merely because one file uses it, instead of proving the convention across representative modules.
• Presenting inferred ownership, deployment topology, or data flow as fact when the repository evidence is incomplete.
• Writing generic onboarding advice that could apply to any repository and omits the actual commands, entry points, and constraints.
• Shipping illustrative template values, placeholder tables, or diagrams whose nodes and edges were not observed in the repository.
• Mining review history without authorization or fabricating a team quality bar when hosting data is unavailable.

Decision rules it applies

• Trace at least one representative runtime flow from entry point to side effect before naming the architecture.
• Prefer defining manifests, executable configuration, and implementation files over generated output or secondary prose as evidence.
• Label a claim as inferred when no source directly establishes it, and name the exact check that would confirm it.
• Keep the quick start to commands present in the repository and separate executed evidence from commands that remain unverified.
• Document component, data, and API sections only when those surfaces exist, explicitly recording a verified absence rather than inserting placeholders.
• Generate the contributor playbook only from authorized, resolved review history and keep it separate from source-derived architecture facts.

Evidence it asks for

• Use the repository file tree, package or solution manifests, and executable entry points to establish the initial system boundary.
• Run the smallest documented build or test command and record its exit result, prerequisites, and produced artifact.
• Search symbol references from public routes or handlers into services and persistence to validate a representative dependency chain.
• Compare source ownership and deployment files against the proposed module and runtime map before publishing the overview.
• Enumerate routes, schemas, migrations, models, and external clients from their registrations and trace representative calls into implementations.
• When authorized, sample merged pull requests and resolved review threads across components before ranking contributor playbook patterns.

The method inside

1. Resolve the repository identity, revision, output path, audience, and whether an authorized pull request history should produce a separate contributor playbook.
2. Inventory the repository tree, executable entry points, manifests, lock files, infrastructure, build paths, and exact technology versions before naming the architecture.
3. Trace representative runtime and data flows, then map major components, defining classes or interfaces, storage models, APIs, authentication, and external integrations in parallel where scopes do not overlap.
4. Draft a source-cited overview with purpose, stack, architecture diagrams, project structure, application components, data architecture, API specifications, setup, and explicit unknowns; never retain illustrative placeholders.
5. If requested and authorized, mine resolved merged pull request reviews into a separate team playbook covering recurring accepted feedback, quality bars by area, tribal knowledge, and reviewer ownership.
6. Review every major claim against current source, execute documented commands where practical, validate diagram edges, and report omissions or unverified evidence rather than inventing completeness.

Deliverables

• Source-cited repository overview with purpose, exact technical stack, architecture diagrams, project structure, setup, and key module dependencies
• Application component, data architecture, API contract, authentication, and external integration maps with verified absences and open questions
• Optional contributor team playbook derived from authorized resolved pull request history, plus a claim-verification and command-results appendix

Evidence requirements

• Repository root, immutable revision, manifests and lock files, source code, infrastructure, tests, build scripts, and existing documentation
• Executable entry points, component registrations, schemas, migrations, routes or interface definitions, authentication, and external client configuration
• Audience, desired output path, environment constraints, and authorization to access merged pull request review history when a team playbook is requested

Quality gates

• Every material claim traces to supplied evidence or is labeled as a hypothesis.
• The response follows the declared deliverable contract.
• No execution, access, measurement, or verification is invented.
• Secrets and personal data are redacted rather than repeated.
• The user receives a concrete independent verification step.
• The relevant failure modes in this domain were considered rather than only the reported symptom.
• No listed anti-pattern was recommended as a solution.