guide-and-manual

Produce two progressively layered development documents for landing a tech decision: a getting-started guide and a detailed manual. This skill provides a general methodology applicable to any technology landing — communication channels, storage solutions, UI architecture rewrites, introducing new frameworks, etc. Add the project's own practice cases as appendices.

When to use

Trigger when the user shows any of the following intents:

1. "Decided to use X for Y, give detailed guidance + official references so newcomers can get started" → produce the Development Guide.
2. "Based on the guide + reference materials + project code and constraints, give a development flow refined to each class/function, onboarding-friendly, with each stage independently verifiable" → produce the Detailed Development Manual.
3. Run both stages in one pass → guide first, then manual.

You may complete both in one pass or split into two runs (guide first, then manual after the user confirms). The manual must treat the guide as required prerequisite reading and not repeat concepts.

When NOT to use

• Do not use for a post-hoc recap of work already done — use dev-recap-docs instead.
• Do not use when only one of the two documents is needed and the user explicitly excludes the other; the two are designed as a complementary pair.
• Do not use as a substitute for the decision document itself — the guide and manual reference the decision document, they do not replace it.

Deliverables

The two are complementary: the guide builds the mental model; the manual gives the steps. The manual does not restate concepts already in the guide — it links back to the guide at the start.

Step 1: Gather the input materials (7 categories to confirm before writing)

Document quality depends on whether inputs are complete. Before writing, gather the following materials in the repository. When a category is missing, mark it ⚠️ TODO in the document; do not fabricate it.

When category 5 (project skeleton) cannot be found: it means this capability has no skeleton yet. Confirm with the user whether an abstraction layer (interface + stub placeholder) should be built first, then generate the manual — the manual's "foundation swap" pattern depends on a skeleton already existing.

Core methodology (10 principles, spanning both stages)

Each principle is a general method; the parenthetical cases are examples only:

1. Two progressively layered stages with complementary responsibilities — The guide builds the mental model (why + concepts + official references + full pitfall table + verification route); the manual gives the steps (class/function level + per-stage verification). The manual treats the guide as prerequisite reading and does not repeat concepts.
2. Anchor on the existing code skeleton ("foundation swap" thinking) — Do not design from scratch. Frame the work as "replace the placeholder / old implementation with the real implementation". Identify the existing abstraction layer (interfaces / repositories / state machines / domain models / built skeletons) first; organize everything through a mapping table of "existing abstraction → what the real implementation must do / what stays untouched", explicitly marking upper layers as unchanged.
   • Example: the manual's "Mapping to existing code" + "Integration points" tables mark the upper-layer callers as unchanged and only swap the stub implementation for the real one.
3. Manage reference materials differently — The three reference types serve different purposes; do not mix them:
   • Decision document (why) → prerequisite reading for the guide.
   • Real prior-art walkthrough (what an industrial-grade version looks like) → reference for layered model + interface contract.
   • Runnable demo (a working project) → reusable code files; rate each file with ★.
   • Explicitly state where the current project differs from the reference demo and why those changes were made.
   • Practice example: signaling switched from the demo's WebSocket to HTTP /offer because zero cloud dependency was desired.
4. Verification route from fake to real (incremental variable growth) — smoke check → local loopback → fake dependency / stub → real integration → boundary / security → optional items. Each stage must be independently verifiable; do not enter the next stage before the current one passes. The guide gives the route overview; the manual gives concrete verification per stage (including expected output).
   • Example: smoke (minimum observable signal) → loopback self-test → fake peer / stub → real integration → boundary-condition verification (network drop / timeout / abnormal input).
5. Concepts first, analogy-driven — Build the mental model at the start of the guide: one-sentence definition + everyday analogy + N core concepts + "why there is no single right answer" (when the technology has design degrees of freedom). Target readers with zero background.
   • Example: explain abstract technical concepts using everyday analogies (e.g., compare protocol handshake to the dial-connect-talk flow of a phone call).
6. Four-part structure per stage (core shape of the manual) — Each stage must contain: ① Goal (one sentence: what this stage produces) ② New classes / changes (complete copy-pasteable code, including package / import / KDoc) ③ Implementation notes (inline-mark pitfalls with their number) ④ Verification (commands + expected output + unit tests + fake-dependency expectations).
7. Pitfall list spans three locations — Guide: full pitfall table (pitfall / correct practice). Manual: quick-reference table (pitfall / correct practice / corresponding stage). Code comments: inline pitfall #N markers. Numbering stays consistent across both documents.
8. Constraint alignment — All code obeys the project's existing constraints (extracted from the project's constraint docs such as CLAUDE.md / CONTRIBUTING.md / architecture decision records): architecture pattern, DI style, async / concurrency model, error-handling convention, logging convention, serialization convention.
9. Verify current state; do not blindly trust the decision document — If the decision doc says "introduced" but the build config does not actually include it, flag it honestly: ⚠️ Not yet introduced as of current state; the first step must add it. If a placeholder (Stub) exists, organize the document around "replace the stub".
   • Example: §4 of the guide opens by verifying "the decision doc lists it in the tech stack, but the build config file does not actually include it".
10. External collaboration contracts, frozen — Whenever an interface, protocol, data format, or threshold involves an external team / system / peer, freeze it into a "Delivery contract" section. Mark who delivers the external implementation; mark pending selections as TBC. When there is no external collaboration party, this principle may be omitted.

Stage 1: Generate the Development Guide

Structure template (order is a reference; trim to fit the technology)

1. Mental model: what X is — one-sentence definition + analogy table + N core concepts (each with a "use in this project" column) + "why there is no single right answer" (when the technology has design degrees of freedom).
2. Usage in this project and architectural placement — one overview diagram (ASCII architecture diagram, marking each end / each layer + key interactions) + "mapping table to the existing code skeleton" (existing abstraction / location / what the real implementation must do).
3. Core flows (interaction / data / negotiation flows) — first clarify "where this project's flow differs from the reference demo and why" → chosen scheme → sequence diagram (Mermaid sequenceDiagram, including exception branches) → message / data-format examples.
4. Step 1: introduce dependencies (⚠️ verify current state) — first check the actual state of the gradle / manifest, then add the dependency + permissions / config + commands to verify the dependency landed.
5. Step-by-step implementation (slice by slice) — fake to real, core first then optional. Each slice: one block of code + one key point. Recommend "get the core end-to-end path working first, then add optional capabilities".
6. External collaboration interfaces (if any) — responsibilities checklist table + implementation-selection table (mark TBC) + delivery contract (frozen into the doc). Omit this section when there is no external collaboration party.
7. Official references and further reading — grouped: spec and core concepts / libraries used in this project (repo + artifact repo) / underlying sources / isomorphic patterns / candidate implementations from external parties / real prior art.
8. Common pitfalls for newcomers (pitfall list) — full table: # / pitfall / correct practice. Each entry maps to a manual stage.
9. Landing verification route — numbered fake-to-real steps; each step marked "what to verify / dependencies / corresponding manual stage".
10. Reusable resources in this repo — per-file reuse value table for the reference demo (★★★/★★/★ rating + one sentence on "direct reuse value").

Writing rules

• Target readers new to the technology; concepts before code.
• Each "pitfall" must have a corresponding landing in a later manual stage.
• Flag every "decision doc says X but reality is Y" contradiction explicitly; do not silently pick one side.
• Give concrete official links — specific spec section numbers / repo URLs / artifact coordinates — instead of "search for it".

Stage 2: Generate the Detailed Development Manual

Structure template (stage-based)

1. Overview — layered architecture diagram (marking "existing, untouched" vs "new") + new-file location tree + prerequisite interface-extension notes (if interfaces need extending, do it in stage 0).
2. Stage 0: dependencies + config + interface extensions — introduce the library + permissions / config + any necessary interface extensions (e.g., adding methods to an interface) + a synchronized stub implementation of the new methods + verify that compile / tests pass.
3. Stages 1~N: four-part structure per stage (see below).
4. Verification route overview — table: step / what to verify / dependencies / corresponding stage.
5. Integration points with existing code — table: existing code / what the real implementation must do / what stays untouched. End by stating the value of the "foundation swap".
6. Pitfall quick-reference — table: # / pitfall / correct practice / corresponding stage.

Four-part structure per stage (mandatory)

### Stage N: <name>
**Goal**: <one sentence: what this stage produces and what counts as done>

### New classes / changes: `<file path>`
<complete copy-pasteable code: package + import + class/function + KDoc comments>

### Implementation notes
- <bullet points; inline-mark pitfalls as "pitfall #N">

### Verification
- <executable commands: gradlew / curl / adb logcat -s TAG:V>
- <expected output: concrete logcat lines / terminal output / UI state>
- <unit test names, or fake-dependency script snippets>

Code conventions (for code in the manual)

• Complete and copy-pasteable: package + all import statements + class / function body + KDoc. Readers should be able to copy and use it; avoid // ... omitted over key parts, because readers then cannot tell whether the elided code matters.
• Align with project constraints: @Singleton/@Inject, unified Result wrapper, project logging utility, CoroutineScope(SupervisorJob()+Dispatchers.Default), try/finally resource release.
• Inline pitfall markers: in code comments write "pitfall #N" (consistent with the guide's pitfall table).
• Mark TODO / placeholder honestly: when the current state is a Stub / placeholder, comment it as // TODO: real implementation must extend fields; do not pretend it is finished.
• Practice example: stage 4 WebRtcControlService.connect is a complete multi-step orchestration; the PeerConnection.Observer callbacks are all listed (empty implementations are also written, with the reason noted).

Verification conventions

• Commands must be executable (./gradlew :app:dependencies | grep <lib>, curl …, adb logcat -s TAG:V).
• Expected output must be concrete (paste logcat lines, paste fake-dependency terminal output, paste UI text); do not write "you should see success". The point of pasted output is that the reader can diff their result against it.
• Give runnable snippets for fake dependencies (scripts, etc.) so readers can start them locally.
• Make boundary / security verification its own item (e.g., network drop / abnormal input → the fallback behavior the system should exhibit).

Bridging the two stages

• The first item of the manual's "Prerequisite reading (required)" section links back to the guide.
• The manual does not repeat the guide's concept explanations, full pitfall table, or official references — the "pitfall quick-reference" table just links back to the corresponding guide section and adds a "corresponding stage" column.
• The guide's slices and the manual's stages roughly correspond but may be regrouped: the guide splits slices by "conceptual order"; the manual splits stages by "implementation + verification order" (including stage 0 for dependencies / interface extensions).
• Pitfall numbering stays consistent across both documents (guide #1 = manual #1).

Constraints and red lines

1. Do not write from memory — every technical detail (API signatures, UUIDs, message formats, constant values, version numbers) must come from code / reference docs / official materials. Filling gaps with generic knowledge risks subtle drift between the doc and the actual API.
2. Do not draw only the happy path — sequence diagrams and flow diagrams must include failure / timeout / cancellation / exception branches, because readers will hit them first in production.
3. Do not skip verification — every manual stage must have executable verification + expected output; if a stage has no built-in verification mechanism, document "how to trigger it manually".
4. Do not fabricate UUIDs / messages / constants — pull actual values from code or contract docs; mark placeholders / TODOs honestly, since invented values look authoritative and mislead readers.
5. Do not break existing abstractions — the document is organized around "foundation swap"; do not change upper-layer settled interfaces unless stage 0 explicitly extends them and gives a reason + a synchronized stub.
6. Do not paper over uncertainty — when the decision and the implementation disagree, or an external selection is pending, mark it ⚠️ TODO verify / TBC instead of silently picking one side, because silent choices become very expensive to reverse later.
7. Do not delete the user's existing logs or modify code beyond the document's scope — this skill only generates documents; it does not modify source code (the code inside the document is a template for readers to follow, not a patch to drop directly onto disk).
8. Keep section numbering continuous — after adding a section, check the numbering; pitfall numbering stays consistent across both documents.

Follow-up actions after completion (suggest to the user; do not run automatically)

After both documents are generated, suggest the following wrap-up to the user:

• Run the readme-sync skill to check whether the project's onboarding / getting-started docs need an "anti-stale" update.
• Run the project's change-archiving flow (change record / PR description / ADR / commit message) to archive this implementation.
• If the decision document contains phrases like "pending at some stage", "TBC", or "already in the tech stack but actually not introduced" that need correcting, suggest the user fix them in the same pass.
• The project's progress-tracking document (if any) may be updated as needed (via the phase-tracking skill).

Practice reference exemplars

The methodology itself is fully general. If the project already contains a successful landing instance of this skill (a development guide + manual for some technology), you may cite it in an SKILL.md appendix as a comparison exemplar — but the methodology does not depend on any specific tech stack or scenario. When generating documents for other technologies / scenarios, apply the methodology and structure directly.