# unknown > Produce a structure-mirrored, evidence-first technical handbook from a repository. - Author: Jacky Chan - Repository: JackyCZJ/repo2doc - Version: 20260210100511 - Stars: 0 - Forks: 0 - Last Updated: 2026-02-10 - Source: https://github.com/JackyCZJ/repo2doc - Web: https://mule.run/skillshub/@@JackyCZJ/repo2doc~unknown:20260210100511 --- --- name: repo2doc description: Deep repository architecture analysis and evidence-based documentation generation. Use when the user provides a Git URL (or local repo path) and wants: (1) architecture/source-code deep dive, (2) module and flow analysis, (3) a detailed clickable handbook mapped to project structure, and (4) module-specific documentation files named after real modules. --- # repo2doc Produce a structure-mirrored, evidence-first technical handbook from a repository. ## Inputs Collect these inputs before execution: - Repository source: Git URL or local path - Target revision: branch/tag/commit (default: default branch) - Output root (default: `Report//`) - Depth mode: `standard` or `audit` - Language preference for output If the repository is remote, clone it locally first. ## Workflow ### 1) Baseline and inventory - Lock analysis revision (record branch + commit hash). - Detect language/runtime/build entrypoints. - Build a directory map and identify major domains/modules. - Extract config surfaces (`.env*`, yaml/json/toml configs, CI, deployment files). Write baseline metadata and navigation to `Report//00-reading-guide.md`. ### 2) Architecture decomposition Analyze top-down: - System boundary: external dependencies, service boundaries, data stores - Layering pattern: API/application/domain/infrastructure (or equivalent) - Runtime shape: monolith, service split, workers, jobs, schedulers - Cross-cutting concerns: auth, logging, metrics, tracing, error handling Write architecture output to `Report//system-overview.md`. ### 3) Flow and module deep dive Select core user/business flows first, then trace code paths: - Entry -> orchestration -> domain logic -> persistence/integration -> return path - Include error paths, retries/timeouts, and failover behavior where present - Map important modules to responsibilities and key interfaces Write outputs to: - `Report//module-map.md` - `Report//core-flows.md` - `Report//.md` (one file per major module; use real module names, not template names) ### 4) Data and operations view Document: - Data models and state transitions - Configuration hierarchy and precedence - Startup/run/deploy behavior - Observability points (log/metric/trace hooks) Write outputs to: - `Report//data-and-state.md` - `Report//runtime-and-config.md` ### 5) Risk and improvement plan Classify findings by severity: - `P0`: security/correctness failures, fail-open auth, critical data integrity risk - `P1`: high-impact stability/performance/operability issues - `P2`: maintainability/documentation/developer-experience debt For each finding include: trigger, impact, evidence, fix direction, verification check. Write outputs to: - `Report//risks-and-techdebt.md` - `Report//optimization-roadmap.md` ### 6) Evidence index and linkability - Add a source index with all cited files. - Ensure every major conclusion links to source references in `path:line` format. - Keep headings stable and anchor-friendly. Write source index to `Report//appendix-source-index.md`. ## Documentation guidance Use `references/spec.md` as guidance. Default quality goals: - Evidence-first: important claims require code/config evidence. - Structure mirror: chapter structure follows repository layout. - Layered readability: executive view before module details. - Actionable findings: each risk has fix + validation guidance. - No fluff: avoid generic text without repository-specific evidence. ## Optional quality checks Validation is optional and should not block report generation by default. - Scaffold: `scripts/scaffold-report.sh --modules ` - Validate (warn-only default): `scripts/validate-report.sh ` - Validate (strict + fail on errors): `scripts/validate-report.sh --strict --enforce` ## Output checklist Deliver all of the following: - Full handbook files under `Report//` - `project-overview.md` (installation, usage, basic QA) - Module deep-dive files named by real modules (for example: `auth-service.md`, `scheduler.md`) - Deep-dive sections must be project-adaptive (for example: state machine, temporal behavior, mechanism implementation/flow), not rigidly fixed - Include Mermaid diagrams as embedded markdown blocks by default; do not require SVG generation unless explicitly requested - Clickable table of contents in `00-reading-guide.md` - Risk register with `P0/P1/P2` - Source evidence index (`appendix-source-index.md`) - Short “analysis limitations” note for unverified assumptions ## Escalation triggers Call out blockers early if: - Missing dependencies prevent static/dynamic verification - Monorepo scope is too large for one pass - Build scripts are non-deterministic or environment-coupled When blocked, still ship a partial report with explicit gaps and next verification steps.