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:

• Check for git remote: Run git remote get-url origin to detect if a remote exists
• 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
• Local-only → use local citations: (file_path:line_number)
• Determine default branch: Run git rev-parse --abbrev-ref HEAD
• 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:

| Guide | Audience | What You'll Learn | Time |

|-------|----------|-------------------|------|

| Contributor Guide | New contributors with Python/JS experience | Setup, first PR, codebase patterns | ~30 min |

| Staff Engineer Guide | Staff/principal engineers | Architecture, design decisions, system boundaries | ~45 min |

| Executive Guide | VP/directors of engineering | Capabilities, risks, team topology, investment thesis | ~20 min |

| Product Manager Guide | Product managers | Features, user journeys, constraints, data model | ~20 min |

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)

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

Part II: This Codebase

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

Part III: Getting Productive

• Prerequisites & Setup — Table: Tool, Version, Install Command. Step-by-step with expected output at each step.
• 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

• Executive Summary — What the system is in one dense paragraph. What it owns vs delegates.
• The Core Architectural Insight — The SINGLE most important concept. Include pseudocode in a DIFFERENT language from the repo.
• System Architecture — Full Mermaid graph TB diagram. Call out the "heart" of the system.
• Domain Model — Mermaid erDiagram of core entities. Data invariants table: Entity, Invariant, Enforced By, Source.
• Key Abstractions & Interfaces — classDiagram showing load-bearing abstractions.
• Request Lifecycle — sequenceDiagram (with autonumber) showing typical request from entry to response.
• State Transitions — stateDiagram-v2 for entities with meaningful lifecycle states.
• Decision Log — Table: Decision, Alternatives Considered, Rationale, Source.
• 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

• System Overview — What it does, who uses it, business value in 2-3 sentences
• Capability Map — Table: Capability, Status (Built/Partial/Planned), Maturity, Dependencies. What the system can and cannot do today.
• 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.
• Team Topology — Which team/person owns which components. Table: Component, Owner, Criticality, Bus Factor.
• Technology Investment Thesis — Why these technologies were chosen. Table: Technology, Purpose, Alternatives Considered, Risk Level.
• Risk Assessment — Table: Risk, Likelihood, Impact, Mitigation, Owner. Cover reliability, security, scalability, compliance.
• Cost & Scaling Model — How costs scale with usage. What the bottlenecks are. When the next scaling investment is needed.
• Dependency Map — graph TB showing critical external dependencies. Table: Dependency, Type (Service/Library/Platform), Risk if Unavailable.
• 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

• What This System Does — 2-3 sentence elevator pitch in user-facing language (no jargon)
• User Journey Map — Mermaid graph LR or journey diagram showing primary user flows through the system
• 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.
• 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").
• Configuration & Feature Flags — Table: Flag/Config, What It Controls, Default, Who Can Change It. What can be toggled without engineering work.
• API Capabilities — What integrations are possible. Table: Capability, Endpoint/Method, Authentication, Rate Limits. Written for integration partners, not developers.
• Performance & SLAs — Response times, throughput limits, availability targets. Table: Operation, Expected Latency, Throughput Limit, Current SLA.
• Known Limitations & Constraints — Honest list of what the system can't do or does poorly. Table: Limitation, User Impact, Workaround, Planned Fix.
• 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