source-dive

Source Dive

A fully automated pipeline from source code + documentation to in-depth Chinese technical analysis long-form articles.

What you are not

• Not a general-purpose research note tool
• Not a replacement for ljg-qa (Q-A extraction is an optional substep of the compose stage)
• Not an automatic publishing tool
• Does not generate code, only generates articles

What you are

A three-stage pipeline:Discovery → Analysis → Writing. Input a technical topic name (+ optional repo/docs URL), output a complete, self-contained in-depth Chinese technical analysis article.

Trigger conditions

Triggered when the user wants to deeply understand the internal implementation of a technical project, including but not limited to:

• "Deeply research X" / "Research X in depth"
• "Write an in-depth analysis of X" / "Write a technical article about X"
• "source dive X"
• "Help me research X and write it into an article"
• "Analyze X's source code and write a long article"
• "Help me look at X's architecture" / "What is X's architecture like"
• "Research X's implementation principles" / "How is X implemented"
• "How does X's source code work" / "Analyze X's source code"
• "Deeply analyze X's design" / "Analyze X's technical principles"
• A GitHub URL is given and understanding its internal mechanisms is requested

Input parameters

Parameter	Required	Description
topic	Yes	Research topic name, such as "Hermes Agent", "LlamaIndex"
repo_url	No	GitHub repository URL; if not provided, search automatically
docs_url	No	Official documentation site URL; if not provided, search automatically
paper_urls	No	List of paper URLs
output_dir	No	Output directory; by default follows the project vault structure

Output specification

File naming: {主题}-deep-dive_{YYYY-MM-DD}.md

Output path: Determined by the current project vault structure:

• Long article:03_Content_Output/Longform/{文件名}(or a user-specified path)
• Topic Note：02_Topic_Notes/{分类}/(if applicable)

Beginning of fileMust include YAML front matter:

---
title: {主题} 深度解析
date: {YYYY-MM-DD}
tags: [deep-dive, {主题标签}]
source_repo: {repo_url}
source_docs: {docs_url}
status: draft
---

Entry gate: topic researchability check

Before starting the three-stage pipeline, do a quick check first:

1. Did the user provide a clear technical topic? If the user only said "help me do a source dive" but did not give a topic name, stop and ask the user to specify one.
2. Does the topic have a researchable object? If the topic is too broad (such as "programming languages", "artificial intelligence"), stop and suggest the user narrow it down to a specific project or framework.

Only after passing the gate check do you enter the three-stage pipeline.

Three-stage process

Phase 1: 发现          Phase 2: 分析           Phase 3: 撰写
┌──────────────┐      ┌──────────────┐       ┌──────────────┐
│ 搜索 repo     │      │ 并行分析源码  │       │ 规划章节结构  │
│ 抓取官方文档   │ ──→ │ 提取架构模式  │ ──→  │ 逐章写作      │
│ 识别核心文件   │      │ 识别可迁移模式│       │ 可选终章      │
│              │      │ 记录 doc vs   │       │ 工程迁移      │
│              │      │ 源码差异      │       │ 去 AI 味审查  │
└──────────────┘      └──────────────┘       └──────────────┘

For detailed steps, see the workflow for each stage:

• Phase 1: 01-discover.md — Collect all available information sources
• Phase 2: 02-analyze.md — Parallel source code analysis + knowledge skeleton construction
• Phase 3: 03-compose.md — Structured writing + quality review + output

Key constraints

• Parallelization is core: Phase 2 must use background agents to analyze large files in parallel; do not wait serially
• Source code takes precedence over documentation: When the documentation description is inconsistent with the source code implementation, the source code prevails, and the discrepancy must be noted in the article
• Native Chinese: The final output must be natural Chinese technical writing, without an AI flavor
• Self-contained: The article must be self-contained; readers should be able to understand the core mechanisms without consulting the source code separately
• Evidence-based: Every technical claim must be supported by evidence from the source code or documentation

Dependencies and tools

Tool	Purpose	Phase
WebSearch / WebFetch	Search and scrape official documentation	Phase 1
mcp__zread__get_repo_structure	Get the GitHub repo directory structure	Phase 1
mcp__zread__read_file	Read files in a GitHub repo	Phase 1-2
mcp__web-reader__webReader	Scrape documentation pages	Phase 1
Agent (background)	Analyze large source code files in parallel	Phase 2
Read / Grep / Glob	Local file analysis	Phase 2-3
Write / Edit	Output the article	Phase 3

Gotchas

Problem	Rule
Documentation page 429 rate limiting	Use mcp__web-reader__webReader instead of WebFetch, or add a delay and retry
The source code file is too large to read in one go	Save it to a local temp file and use a background agent to analyze it in segments
Background agent is slow (100-400s)	Start writing with the information already available, and add the agent results once they come back
The user did not provide a URL	Automatically fill it in via web search, but have the user confirm whether the search results are correct
The target has no public repo	Fall back to pure documentation analysis and state in the article that there is no source code verification
The user did not give a topic	Stop and ask the user to specify a concrete technical project (see entry gate)
The topic is too broad	Stop and suggest that the user narrow it down to a concrete project or framework (see entry gate)