wiki-onboarding

Wiki Onboarding Guide Generator

Generate four audience-tailored onboarding documents in an onboarding/ folder, each giving a different stakeholder exactly the understanding they need.

Source Repository Resolution (MUST DO FIRST)

Before generating any guides, you MUST determine the source repository context:

1. Check for git remote: Run git remote get-url origin to detect if a remote exists
2. Ask the user: "Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"
   • Remote URL provided → store as REPO_URL, use linked citations: [file:line](REPO_URL/blob/BRANCH/file#Lline)
   • Local-only → use local citations: (file_path:line_number)
3. Determine default branch: Run git rev-parse --abbrev-ref HEAD
4. Do NOT proceed until source repo context is resolved

When to Activate

• User asks for onboarding docs or getting-started guides
• User runs /deep-wiki:onboard command
• User wants to help new team members understand a codebase

Output Structure

Generate an onboarding/ folder with these files:

onboarding/
├── index.md                    # Onboarding hub — links to all 4 guides with audience descriptions
├── contributor-guide.md        # For new contributors (assumes Python or JS background)
├── staff-engineer-guide.md     # For staff/principal engineers
├── executive-guide.md          # For VP/director-level engineering leaders
└── product-manager-guide.md    # For product managers and non-engineering stakeholders

index.md — Onboarding Hub

A landing page with:

• One-paragraph project summary
• Guide selector table:

Language Detection

Scan the repository for build files to determine the primary language for code examples:

• package.json / tsconfig.json → TypeScript/JavaScript
• *.csproj / *.sln → C# / .NET
• Cargo.toml → Rust
• pyproject.toml / setup.py / requirements.txt → Python
• go.mod → Go
• pom.xml / build.gradle → Java

Guide 1: Contributor Guide

File: onboarding/contributor-guide.md Audience: Engineers joining the project. Assumes proficiency in Python or JavaScript and general software engineering experience. Length: 1000–2500 lines. Progressive — each section builds on the last.

Required Sections

Part I: Foundations (skip if repo uses Python or JS)

1. {Primary Language} for Python/JS Engineers — Syntax comparison tables, async model, collections, type system, package management. Concrete code side-by-side, NOT abstract descriptions.
2. {Primary Framework} Essentials — Compare to equivalent Python/JS frameworks (e.g., FastAPI, Express). Request pipeline, routing, DI, config.

Part II: This Codebase 3. What This Project Does — 2-3 sentence elevator pitch 4. Project Structure — Annotated directory tree (what lives where and why). Include graph TB architecture overview. 5. Core Concepts — Domain-specific terminology explained with code examples. Use erDiagram for data model. 6. Request Lifecycle — sequenceDiagram (with autonumber) tracing a typical request end-to-end. 7. Key Patterns — "If you want to add X, follow this pattern" templates with real code

Part III: Getting Productive 8. Prerequisites & Setup — Table: Tool, Version, Install Command. Step-by-step with expected output at each step. 9. Your First Task — End-to-end walkthrough of adding a simple feature 10. Development Workflow — Branch strategy, commit conventions, PR process. Use flowchart diagram. 11. Running Tests — All tests, single file, single test, coverage commands 12. Debugging Guide — Common issues table: Symptom, Cause, Fix 13. Common Pitfalls — Mistakes every new contributor makes and how to avoid them

Appendices

• Glossary (40+ terms)
• Key File Reference — Table: Path, Purpose, Why It Matters, Source
• Quick Reference Card — Cheat sheet of most-used commands and patterns

Rules

• All code examples in the detected primary language
• Every command must be copy-pasteable with expected output
• Minimum 5 Mermaid diagrams (architecture, ER, sequence, flowchart, state)
• Use Mermaid for workflow diagrams (dark-mode colors) — add <!-- Sources: ... --> comment block after each
• Ground all claims in actual code — cite using linked format

Guide 2: Staff Engineer Guide

File: onboarding/staff-engineer-guide.md Audience: Staff/principal engineers who need the "why" behind every decision. Deep systems experience, may not know this repo's language. Length: 800–1200 lines. Dense, opinionated, architectural.

Required Sections

1. Executive Summary — What the system is in one dense paragraph. What it owns vs delegates.
2. The Core Architectural Insight — The SINGLE most important concept. Include pseudocode in a DIFFERENT language from the repo.
3. System Architecture — Full Mermaid graph TB diagram. Call out the "heart" of the system.
4. Domain Model — Mermaid erDiagram of core entities. Data invariants table: Entity, Invariant, Enforced By, Source.
5. Key Abstractions & Interfaces — classDiagram showing load-bearing abstractions.
6. Request Lifecycle — sequenceDiagram (with autonumber) showing typical request from entry to response.
7. State Transitions — stateDiagram-v2 for entities with meaningful lifecycle states.
8. Decision Log — Table: Decision, Alternatives Considered, Rationale, Source.
9. Dependency Rationale — Table: Dependency, Purpose, What It Replaced, Source.
10. Data Flow & State — How data moves through the system. Storage comparison table.
11. Failure Modes & Error Handling — flowchart for error propagation paths.
12. Performance Characteristics — Bottlenecks, scaling limits, hot paths.
13. Security Model — Auth, authorization, trust boundaries, data sensitivity.
14. Testing Strategy — What's tested, what isn't, testing philosophy.
15. Known Technical Debt — Table: Issue, Risk Level, Affected Files, Source.
16. Where to Go Deep — Recommended reading order of source files, links to wiki sections.

Rules

• Use pseudocode in a different language to explain concepts
• Use comparison tables to map unfamiliar concepts (e.g., Task<T> = Awaitable[T])
• Dense prose with tables, NOT shallow bullet lists
• Every claim backed by linked citation
• Minimum 5 Mermaid diagrams (architecture, ER, class, sequence, state, flowchart)
• Each diagram followed by <!-- Sources: ... --> comment block
• Use tables aggressively — decisions, dependencies, debt should ALL be tables with Source columns
• Focus on WHY decisions were made, not just WHAT exists

Guide 3: Executive Guide

File: onboarding/executive-guide.md Audience: VP/director of engineering. Needs capability overview, risk assessment, and investment context — NOT code-level details. Length: 400–800 lines. Strategic, concise, decision-oriented.

Required Sections

1. System Overview — What it does, who uses it, business value in 2-3 sentences
2. Capability Map — Table: Capability, Status (Built/Partial/Planned), Maturity, Dependencies. What the system can and cannot do today.
3. Architecture at a Glance — High-level Mermaid graph LR diagram. Services, data stores, external integrations — NO internal code details. Focus on deployment units and team boundaries.
4. Team Topology — Which team/person owns which components. Table: Component, Owner, Criticality, Bus Factor.
5. Technology Investment Thesis — Why these technologies were chosen. Table: Technology, Purpose, Alternatives Considered, Risk Level.
6. Risk Assessment — Table: Risk, Likelihood, Impact, Mitigation, Owner. Cover reliability, security, scalability, compliance.
7. Cost & Scaling Model — How costs scale with usage. What the bottlenecks are. When the next scaling investment is needed.
8. Dependency Map — graph TB showing critical external dependencies. Table: Dependency, Type (Service/Library/Platform), Risk if Unavailable.
9. Key Metrics & Observability — What's measured, what dashboards exist, alerting coverage. Table: Metric, Current Value, Target, Source.
10. Roadmap Alignment — Engineering workstreams mapped to business priorities. What's in progress, what's planned, what's blocked.
11. Technical Debt Summary — Top 5 debt items with business impact. Table: Issue, Business Impact, Effort to Fix, Priority.
12. Recommendations — 3-5 actionable recommendations for the next quarter, prioritized by impact.

Rules

• NO code snippets — this guide is for engineering leaders, not coders
• Diagrams at service/team level, not class/function level
• Every claim backed by evidence — cite wiki sections, architecture docs, or source files
• Minimum 3 Mermaid diagrams (architecture overview, dependency map, capability/roadmap)
• Tables for every structured finding — this audience reads tables, not prose
• Business language — translate technical concepts into impact (reliability, velocity, cost, risk)

Guide 4: Product Manager Guide

File: onboarding/product-manager-guide.md Audience: Product managers and non-engineering stakeholders. Needs to understand what the system does, what's possible, and where the boundaries are — NOT how it's built. Length: 400–800 lines. User-centric, feature-focused, constraint-aware.

Required Sections

1. What This System Does — 2-3 sentence elevator pitch in user-facing language (no jargon)
2. User Journey Map — Mermaid graph LR or journey diagram showing primary user flows through the system
3. Feature Capability Map — Table: Feature, Status (Live/Beta/Planned/Not Possible), User-Facing Behavior, Limitations. Comprehensive map of what's built and what's not.
4. Data Model (Product View) — Simplified Mermaid erDiagram showing entities users interact with. Explain in business terms (e.g., "A Project has many Documents" not "FK relationship").
5. Configuration & Feature Flags — Table: Flag/Config, What It Controls, Default, Who Can Change It. What can be toggled without engineering work.
6. API Capabilities — What integrations are possible. Table: Capability, Endpoint/Method, Authentication, Rate Limits. Written for integration partners, not developers.
7. Performance & SLAs — Response times, throughput limits, availability targets. Table: Operation, Expected Latency, Throughput Limit, Current SLA.
8. Known Limitations & Constraints — Honest list of what the system can't do or does poorly. Table: Limitation, User Impact, Workaround, Planned Fix.
9. Data & Privacy — What data is collected, where it's stored, retention policies, compliance status. Table: Data Type, Storage Location, Retention, Compliance.
10. Glossary — Domain terms explained in plain language (not engineering jargon)
11. FAQ — 10+ common questions a PM would ask, answered concisely

Rules

• ZERO engineering jargon — no "middleware", "dependency injection", "ORM". Use plain language.
• User-centric framing — describe everything in terms of what users experience, not how code works
• Minimum 3 Mermaid diagrams (user journey, data model, feature map/capability overview)
• Tables for every structured finding — PMs scan tables, not prose
• If a technical concept must be mentioned, explain it in one sentence (e.g., "Feature flags — toggles that let us turn features on/off without deploying code")
• Every claim grounded in evidence — cite wiki sections or source files for verification

Mermaid Diagram Rules (ALL guides)

ALL diagrams must use dark-mode colors:

• Node fills: #2d333b, borders: #6d5dfc, text: #e6edf3
• Subgraph backgrounds: #161b22, borders: #30363d
• Lines: #8b949e
• If using inline style directives, use dark fills with ,color:#e6edf3
• Do NOT use <br/> in Mermaid labels (use <br> or line breaks)

Validation

After generating each guide, verify:

• All file paths mentioned actually exist in the repo
• All class/method names are accurate (not hallucinated)
• Mermaid diagrams render (no syntax errors)
• No bare HTML-like tags (generics like List<T>) outside code fences — wrap in backticks
• Each guide is appropriate for its audience — no code in Executive/PM guides