/dev-guide-generator

name: dev-guide-generator
description: "Generates complete technical tutorials from prerequisites and environment setup to core steps, troubleshooting, and a final cheatsheet. Trigger on requests to write a tutorial, create a setup guide, organize steps for beginners, or keywords like step-by-step, quickstart, or how-to guide."
license: MIT

Dev Guide Generator

**One topic → complete technical tutorial**: Through a structured SOP workflow, transform a technical topic into a comprehensive tutorial covering prerequisites, environment setup, core steps, common error troubleshooting, and advanced topics — all accompanied by a cheatsheet.

Quick Start

The user simply provides a technical topic or operational goal, and the Agent automatically generates a complete tutorial following this workflow:

User: Help me write a Docker beginner's tutorial
Agent: [Outputs complete technical tutorial + Cheatsheet following the SOP workflow]

SOP Workflow

Phase 1: Topic Scoping & Audience Analysis

**Goal**: Define the tutorial's technical subject, target audience, and scope boundaries.

**Steps**:

1. **Parse the topic**: Identify the core technology, operational goals, and expected deliverables from the user's input 2. **Ask clarifying questions** (up to 4 key questions):

• What is the target audience's technical level? (Complete beginner / Some experience / Experienced developer)
• What operating system will the reader be using? (macOS / Windows / Linux / Any)
• What should the reader be able to do after completing the tutorial? (Specific deliverable)
• Are there any version or tech stack constraints?

3. **If the user asks to skip clarification**, proceed with these default assumptions:

• Audience: Has basic programming experience but is unfamiliar with the topic technology
• Environment: Cover both macOS and Linux (note Windows differences where necessary)
• Goal: Be able to independently complete a minimal working example

**Output**: Tutorial metadata summary (topic, audience, objective, scope — no more than 150 words)

---

Phase 2: Prerequisites

**Goal**: List all knowledge and tools the reader needs before starting this tutorial, ensuring there are no knowledge gaps.

**Steps**:

1. **Dependency analysis**:

• List all technical concepts involved in this tutorial
• For each concept, determine whether it should be "explained within the tutorial" or "assumed as prior knowledge"
• Decision rule: If explaining it would digress more than 200 words from the main topic, classify it as a prerequisite

2. **Prerequisites checklist**:

• Categorize into "Must know" and "Nice to know" tiers
• Attach a one-line explanation for each: "why you need it"
• Format:

     **Must know**:
     - [Concept]: [Why you need it] (Recommended resource)

     **Nice to know**:
     - [Concept]: [What aspects of the tutorial it relates to]

3. **Self-check rules**:

• If prerequisites exceed 5 items, consider narrowing the tutorial scope or splitting into a series
• Every prerequisite must have a publicly available learning resource

**Output**: Tiered prerequisites checklist

---

Phase 3: Environment Setup

**Goal**: Provide a reproducible environment configuration path so the reader is fully set up before starting the core steps.

**Steps**:

1. **Environment inventory**: List all tools to install/configure with recommended versions

• Format: `Tool name Version requirement (e.g., >= x.y) | Purpose`
• Clearly distinguish "required" from "optional" installations

2. **Installation steps**: Provide commands for each operating system

• Precede each command with a one-line explanation of what it does
• Use only officially recommended methods or mainstream package managers
• Format:

     **macOS**:
     # Install xxx (via Homebrew)
     brew install xxx

     **Linux (Ubuntu/Debian)**:
     # Install xxx (via apt)
     sudo apt update && sudo apt install -y xxx

3. **Environment verification**: Provide a verification command and expected output after each tool installation

• Format:

     # Verify installation
     xxx --version
     # Expected output: xxx x.y.z

4. **Self-check rules**:

• All installation commands must come from official documentation or mainstream package managers — no third-party scripts
• Never include real API keys, passwords, tokens, or other sensitive values
• When configuration files are involved, use placeholders (e.g., `YOUR_API_KEY`) and explain how to obtain the real value

**Output**: OS-specific installation and configuration guide + verification commands

---

Phase 4: Core Steps

**Goal**: Walk the reader through the core operations in a progressive structure, where each step can be independently verified.

**Steps**:

1. **Step planning**:

• Break the entire operation into 5–10 steps (each focused on one sub-goal)
• Order steps strictly by dependency
• Each step includes: step number, title, and objective statement

2. **Step writing format**:

   #### Step N: [Step Title]

   **Objective**: [What state is achieved after this step]

   **Actions**:
   [Code block or operational instructions]

   **Explanation**:
   - [Line-by-line or section-by-section explanation of key parts]

   **Verification**:
   [What command to run / what result to check to confirm success]
   Expected output: [Specific expected result]

3. **Writing guidelines**:

• Code blocks must specify the language (e.g., ```bash, ```python)
• Placeholders use ALL_CAPS_WITH_UNDERSCORES format (e.g., `YOUR_PROJECT_NAME`) and are explained on first occurrence
• Each code block should not exceed 30 lines; split and explain in sections if longer
• Use relative file paths; state the project root directory at the beginning
• Every step must end with a verification section

4. **Progressive complexity**:

• Steps 1–3: Minimal runnabl