Engineering Onboarding Guide

---
name: engineering-guide
description: Analyzes a scope (a whole repo, a folder, a feature, or a single package) and produces a comprehensive engineering onboarding guide for a human engineer. The output accelerates a new engineer's ability to start coding by explaining architecture, layers, data, patterns, and tribal knowledge of that scope. Use when the user says "engineering guide", "onboarding guide", "write an onboarding doc", "explain this app/service/package/folder", "deep dive on X", "write a guide for X", "document this feature/module", "generate an engineering guide", or when the user points at a specific path (e.g. "apps/ms-profile", "libs/foo", "the billing feature") and asks for a comprehensive walkthrough.
argument-hint: [scope — path, package, or feature description]
---

# Engineering Guide

Analyze a user-specified scope and produce a comprehensive engineering guide aimed at a human engineer who is about to start coding in that area. The goal is to compress weeks of tribal-knowledge onboarding into a single readable document.

`$ARGUMENTS` may be:
- A path (e.g., `apps/ms-profile`, `libs/infrastructure`, `src/features/billing`)
- A package name (e.g., `@pc-services/ms-cards`)
- A feature or domain description (e.g., "the authorization flow", "RLS scoping")
- Empty — default to the entire current repository

## Workflow

### 1. Clarify the scope

- Resolve `$ARGUMENTS` to concrete paths. If ambiguous (e.g., "the billing feature"), grep/glob to find the relevant files and confirm the set before going deep.
- If no scope is given, default to the full repository.
- State the resolved scope back to the user in one sentence before going deep (e.g. "Reviewing `apps/ms-profile` — a NestJS service under the monorepo.").
- Ask the user where to write the output. Sensible defaults:
  - Scope = whole repo → `./ENGINEERING_GUIDE.md`
  - Scope = a subfolder → `<scope>/ENGINEERING_GUIDE.md`
  - Otherwise → ask.

### 2. Discover

Read project-level context first to situate the scope:

- Root-level `CLAUDE.md`, `README.md`, `AGENTS.md`, `CONTRIBUTING.md` if present
- Package manifest(s): `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.
- Monorepo config: `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`
- Any `CLAUDE.md` or `README.md` inside the scope itself
- Recent git activity in the scope: `git log --oneline -30 -- <scope>` to see what's changing

Then enumerate the scope:

- List the top-level layout of the scope (directories and notable files)
- Open entry points: `main.ts`/`main.py`/`index.*`, `app.module.ts`, `server.*`, `cmd/`, CLI entries
- For each meaningful subdirectory, open 1–3 representative files to understand its purpose — don't try to read everything

### 3. Analyze

For the scope, build an understanding of:

- **Purpose** — what problem does this scope solve, and who calls it?
- **Boundaries** — what's in-scope vs. out-of-scope; what external systems does it touch?
- **Layers / architecture** — controllers, services, repositories, domain models, adapters, etc. What are the responsibilities of each layer and how do they depend on each other?
- **Data model** — entities, tables, schemas, key relationships, ownership/RLS/multi-tenancy rules
- **Features** — high-level list of user-facing or API-facing features this scope provides
- **Request/data flow** — trace 1–3 important paths end-to-end (an API call, a background job, an event handler)
- **Configuration** — env vars, secrets, feature flags, per-environment differences
- **Infrastructure** — where it runs locally, where it runs in prod, how it's deployed
- **Testing** — what kinds of tests exist, how to run them, what's mocked vs. real
- **Key patterns & conventions** — error handling, logging, validation, auth guards, DI, naming
- **Cross-cutting concerns** — observability, tracing, metrics, rate limiting, retries
- **Tribal knowledge** — things you only find out by reading git log, comments, or CLAUDE.md (past incidents, "don't touch this", surprising constraints)

Stay proportional: deeper scope → deeper depth. For a single feature, trace the code precisely. For a whole repo, stay higher-level and link down to key files.

### 4. Write the guide

Write the output to the agreed path using the structure below. Use concrete file paths (`apps/ms-profile/src/foo/bar.service.ts:42`) everywhere so the reader can jump straight to code. Prefer short, declarative sentences over paragraphs. Show one real code snippet per pattern rather than describing it abstractly.

---

```markdown
# Engineering Guide — <Scope Name>

> Audience: an engineer who has never touched this code and wants to start contributing today.

## 1. What This Is
1–3 sentences: what this scope is, who it serves, and the problem it solves. Include how it fits into the larger system if relevant.

## 2. TL;DR for the Impatient
- 5–8 bullets. The "if you only read this section" summary.
- Include: primary responsibility, key tech, main entry point, where to add a new feature, where tests live, how to run it locally.

## 3. Tech Stack
Table of: language, framework, runtime, database, queue/messaging, cloud services, IaC tool, key libraries. One row each.

## 4. Layout
Annotated tree of the scope. One-line purpose per directory:

\`\`\`
<scope>/
├── src/
│   ├── modules/         — feature modules, one per domain area
│   ├── common/          — shared guards, filters, interceptors
│   └── main.ts          — bootstrap
├── test/                — e2e tests
└── infrastructure/      — Pulumi program for this service
\`\`\`

## 5. Architecture
Describe the layers and how they interact. If useful, include a small ASCII or Mermaid diagram showing:
- Runtime components (HTTP server, workers, listeners)
- Data stores and caches
- External services called
- How requests and events flow in/out

## 6. Domain & Data Model
- Core entities and their relationships (one paragraph or a mini ER description).
- Where the schema lives (Prisma/SQL/ORM file paths).
- Ownership / tenancy / RLS rules that affect every query.
- Migration workflow, if non-obvious.

## 7. Features
A short catalog of the features/capabilities this scope provides. For each:
- **Name** — one-line description
- **Entry point(s)** — route/handler/job file paths
- **Key files** — 2–3 most important files

Keep this scannable — the reader uses it as an index.

## 8. Walkthroughs
Pick 1–3 representative flows and trace them end-to-end with file:line references. Examples:
- "Creating an account" — controller → service → repo → DB → event
- "Importing an EFS card file" — SFTP trigger → parser → domain → integration client → persistence
- "Background reconciliation job" — cron → worker → external API → DB update

Each walkthrough should read like a guided tour, not a theorem proof.

## 9. Cross-Cutting Concerns
- **Auth & authorization** — guards, decorators, how identity flows in
- **Validation** — DTOs/schemas, where they live
- **Error handling** — filters, conventions, what gets logged vs. returned
- **Logging & observability** — logger, correlation IDs, traces, metrics
- **Configuration** — env vars, feature flags, per-env differences
- **Caching / rate limiting / retries** — if applicable

## 10. Testing
- What kinds of tests exist (unit, integration, e2e) and where they live.
- How to run them locally (exact command).
- What's mocked vs. hit for real (DBs, external APIs).
- Test data / fixtures strategy.

## 11. Local Development
- Prerequisites (runtimes, tools, credentials).
- Exact commands to install, build, run, and hot-reload.
- What other services (DB, queue, emulators) must be running.
- Minimal env vars needed and where to get values.

## 12. Deployment & Environments
- Where it runs in prod (cloud service, region).
- How it gets there (CI pipeline, manual steps, image promotion).
- Environment separation (test/staging/prod) — what differs.
- Where secrets live and how code reads them.

## 13. Conventions & Patterns
Concrete rules the codebase follows. For each, show a real example file:line:
- Naming (files, classes, functions, env vars)
- Module structure
- Dependency injection / wiring
- Error types and thrown-vs-returned errors
- Logging format
- Commit / PR conventions specific to this scope

## 14. Gotchas & Tribal Knowledge
Things the code won't tell you:
- "Don't change X because Y"
- Non-obvious coupling to other services
- Historical decisions that still constrain choices
- Past incidents and the guardrails they left behind
- Performance / scaling cliffs

## 15. Where to Start
If you have to build something here on day one, start by:
1. Reading <file:line>
2. Running <command>
3. Modifying <file:line> as a small warm-up task

## 16. Open Questions / Unknowns
Honestly list things you couldn't determine from the code. Point the reader at the right person or doc. Better to flag gaps than invent answers.
```

---

### 5. Present back to the user

After writing the file, reply with:
- Path of the file written
- A ~5-bullet executive summary of what the scope actually is and does
- Any **open questions** you couldn't resolve from the code — these are the most valuable things to surface

## Guidelines

- **Be concrete.** Every claim should be grounded in a file path or command. If you can't point at code, flag it as an assumption.
- **Be honest about gaps.** "I couldn't determine X from the code" is more useful than a confident guess.
- **Stay proportional.** A single-feature guide is short and deep; a whole-repo guide is broad and shallow with links down.
- **Don't duplicate CLAUDE.md / README content verbatim.** Synthesize, link, and add the glue those docs leave out.
- **Prefer real code snippets over abstract descriptions** when explaining a pattern — one 6-line excerpt beats a paragraph.
- **No fluff.** Skip filler sections that don't apply to the scope. If there are no background jobs, don't invent a "Background Jobs" heading.
- **Keep tone practical and senior.** You're writing to another engineer, not marketing.
- Only write the output file once — don't churn. If the user asks for edits, edit the file in place.