# Deep Tech Article

> Produces verified deep-dive technical articles from a codebase: architecture walkthroughs quoting real source, cookbooks whose every command was actually executed, ADR-style decision stories, and competitive analyses — with diagrams and bilingual output. Use when turning a repository into publishable blog content, documentation, or launch material. Enforces the fact-check protocol that caught 30+ errors in our own first drafts.

- Skill: `zhengqiuyang/deep-tech-article` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhengqiuyang/deep-tech-article`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhengqiuyang/deep-tech-article/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: zhengqiuyang (https://skillmd.com/u/zhengqiuyang)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zhengqiuyang/deep-tech-article

---


# Deep Technical Articles From a Codebase

The failure mode of generated technical writing is confident fiction:
plausible code that never existed, outputs that never ran. This process
makes fiction structurally hard.

## Article types (per repo)

1. **ARCHITECTURE** — module-by-module walkthrough. Quote real code.
2. **COOKBOOK** — recipes; every command executed, output pasted verbatim.
3. **DECISIONS** — ADRs as stories: context → options → decision → consequences.
4. **COMPETITIVE** — landscape with dated evidence and honest kill criteria.

## The writing protocol

1. **Read the source first.** Never describe a module you have not opened.
   Cite symbols by name; an architecture piece should reference ≥5 real ones.
2. **Excerpts are verbatim, with provenance.** Copy from the file, keep the
   file path next to the block. If you elide, mark `...` explicitly. After
   writing, programmatically re-verify excerpts against source (substring
   match after whitespace normalization).
3. **Commands are executed, not imagined.** Build fixtures in temp dirs,
   run the real CLI, paste the real output (trim long runs, never invent
   fields). If a command fails, that is content: fix the doc to match
   reality or record the failure as a finding.
4. **Numbers come from runners**: test counts from `npm test` output, package
   sizes from `npm pack --dry-run`, dates from git log. Recompute totals;
   one observed table didn't sum to its own claimed total.
5. **Diagrams earn their place**: one per major flow, ≤20 nodes, every
   diagram gets a numbered caption and a following paragraph saying what to
   notice. Mermaid with quoted labels; ASCII for decision forks.
6. **Bilingual split**: prose in the audience language; code, commands,
   output, error messages verbatim in original.
7. **Fact-check pass (mandatory, separate from writing)**: verify every
   excerpt, re-run cheap commands, check test counts and versions. Our own
   review waves found: a fabricated JSON output block, a quote with a dropped
   code flag *plus an invented paragraph justifying the mistake*, and stale
   bug states. Assume your first draft contains these too.
8. **Stale-content sweep**: if the code changed since writing (git log),
   update excerpts and claims — especially "open bug" narratives that were
   since fixed.

## Polish rules

导语 (2–4 sentences: why this matters) and 结语 (takeaways) on every major
piece. Unified terminology per family. No shortening during polish — better
flow, more depth, not less content.