| name | Technical Writing |
| description | This skill should be used when the user asks to "write blog post", "technical article", "tutorial", "explain concept", or needs guidance on technical writing for external audiences. Provides patterns for technical blogs and articles in both English and Japanese. Includes a Japanese prose-quality ruleset for drafting and revising Japanese manuscripts, plus a language-neutral long-form structure ruleset for books and serialized pieces. |
| version | 2.2.0 |
Provide structured patterns for writing technical blogs and articles that effectively communicate technical concepts to external audiences.
Write
Read
Edit
WebSearch
mcp__plugin_claude-code-home-manager_context7__resolve-library-id
mcp__plugin_claude-code-home-manager_context7__query-docs
Five types: tutorial (task-based), concept explanation (deep understanding), comparison (decision help), case study (real-world story), opinion piece (best practices)
Capture attention in the first paragraph using problem statement, surprising fact, or relatable story
Lead with conclusion, most important information first, details follow
Demonstrate with working code, diagrams, and before/after comparisons rather than abstract description
Step-by-step guide to accomplish a specific task
Are you teaching readers how to accomplish a specific task?
Create tutorial with step-by-step instructions and working examples
Consider concept explanation for understanding or comparison for decision-making
Developers learning a new skill
Problem statement / What you'll learn
Step-by-step instructions
Troubleshooting common issues
Next steps / Further reading
1500-3000 words
Deep dive into a technical concept
Are you explaining a complex concept for deeper understanding?
Create concept explanation with examples and misconceptions
Use tutorial for task-based learning or opinion piece for best practices
Developers seeking understanding
Analogies and visualizations
When to use / When to avoid
1000-2500 words
Compare technologies, approaches, or tools
Are you helping readers choose between multiple options?
Create comparison with feature analysis and use case recommendations
Use tutorial for implementation or concept explanation for understanding
Developers making technical decisions
Feature-by-feature comparison
Benchmark results (if applicable)
Conclusion with clear guidance
1500-2500 words
Real-world implementation story
Are you sharing a real-world implementation experience?
Create case study with challenge, solution, and lessons learned
Use tutorial for general how-to or opinion piece for best practices
Developers and technical leaders
1500-3000 words
Technical opinion or best practices
Experienced developers
Supporting arguments with evidence
Counterarguments addressed
800-1500 words
<writing_principles>
Capture attention in the first paragraph
Start with a problem the reader faces
Use a surprising fact or statistic
Tell a brief relatable story
Each section should have a single clear purpose
If a section covers multiple ideas, split it
Use headings that summarize the key point
Demonstrate concepts with examples
Include working code snippets
Use diagrams for architecture
Show before/after comparisons
Be concise, get to the point
Lead with the conclusion
Use bullet points for lists
Provide TL;DR for long articles
Build trust through accuracy and honesty
Cite sources and benchmarks
Acknowledge limitations
Show your work (methodology)
<language_guidelines>
Conversational but professional
Confident, helpful, peer-to-peer
First person ("I found that...") or second person ("You can...")
<sentence_length>Vary between short and medium</sentence_length>
Overly formal academic language, buzzwords without substance
่ชญ่
ใจใฎๅฏพ่ฉฑใๆ่ญใใๆไฝ
ๅฐ้็ใ ใ่ฆชใใฟใใใ
ๆ่ก่จไบ: ใงใใปใพใ่ชฟใๅไบบใใญใฐ: ๆ่ปใซ
้ๅบฆใซ็กฌใ่กจ็พใไธป่ชใฎ็็ฅใซใใๆๆงใ
่ฑ่ชใฎๆ่ก็จ่ชใฏ้ฉๅบฆใซใซใฟใซใใงไฝฟ็จๅฏ
Canonical ruleset for drafting and revising Japanese technical prose. Directive text is English; illustrative bad/good examples and Japanese-specific tokens (ไธญ้ปใใปใ, dashesใโใใโใใโโใ, ใใ, footnote [^label], phrases) are kept in Japanese verbatim because they demonstrate Japanese-punctuation and particle norms.
Write one sentence per line; separate paragraphs with a blank line.
Put code, diff, log, and config fragments in code blocks.
Demote side notes (term origins, names of formalizations) to footnotes [^ใฉใใซ] instead of inlining them.
Bullet lists are fine for definitions and classifications; bold the term being defined. Bold a term on its first definition or introduction; for later mentions, quotation, or nicknames use ใใ.
Do not use dashes (em dashใโใ, horizontal barใโใ, double dashใโโใ) in Japanese body text or headings. For appositive or parenthetical insertion (ใAโโๆฟๅ
ฅโโBใ) use parentheses๏ผ๏ผ; for restatement (ใAโโBใ) split into two sentences with ใ or join with ใ. Exception (not covered): en dashใโใfor ranges, English compounds like CurryโHoward, code blocks, and bibliographic info.
Do not use ไธญ้ป๏ผใป๏ผfor Japanese parallel or enumeration. It is allowed only inside a single proper noun.
Do not cram two elements into a heading or column heading with a rule line (็ฝซ็ทใโใU+2500 or dashes) likeใ็จฎๅฅโโไธป้กใใไธป้กโโๆฆๅฟตใ. A heading is a single natural phrase (narrow to one element, or join with a particle or comma). Column headings must not be bare category names likeใๅบ็คใใ่ฃ่ถณใ; specify content, e.g.ใๅๅค้ขไฟใจใใฆใฎๅ้กใใใซใผใไธๅคๆกไปถใจๅธฐ็ดๆณใ.
A bullet listing a term and its definition uses a fullwidth colon, not a rule line:ใ**็จ่ช**๏ผ่ชฌๆใ.
Use paragraph writing (ใใฉใฐใฉใใฉใคใใฃใณใฐ). A paragraph is one step of argument; the reader must follow the logic paragraph by paragraph.
One topic per paragraph. Split long paragraphs that mix multiple scene-progressions (investigation, report, verification, evaluation) into one-step paragraphs.
The first sentence of a paragraph should reveal what the paragraph is about.
At a paragraph's start, make the logical relation to the previous paragraph explicit with a connective (ใใงใใใฐใใๅฎ้ใใใใใใใใใฎไพ่ชไฝใใใใ).
Advance the argument in one direction. Do not use a "conclude then handle objection then restate conclusion" shape. Finish objections and doubts first, then state the conclusion once.
Defenses of an example (looks contrived, pre-empting) must not break the flow mid-climax; handle them together at the start of the next section.
Explicitly deny a likely wrong reading before stating the real reason (ใใใฎ็็ฑใฏใใใ ใใใใงใฏใชใใใใ ใใใ ใ).
When negating withใAใงใฏใชใBใ, add one sentence of grounds for the negation; a counterfactual (ใใใAใชใใใใ ใฃใใ ใใใ) is often usable.
In concession (ใ็ขบใใซใใ), stay at fact confirmation. Do not assert, as the author's voice or as causation, something you later correct (self-contradiction). To provisionally grant a surface diagnosis, attribute it to the reader or common view (ใใใจ่ฆ็ดใงใใฆใใพใใใใใใชใใ).
Do not pre-reveal climax information (figures, specific facts) in the paragraph before the climax.
When negating or limiting, quote the exact proposition being negated in ใใ (e.g.ใๆๆๅใใใฆใใใฐใในใฆใไปปใใใใใใๆๅณใใชใ); do not settle for vague negation likeใไฝใใใใ่งฃๆฑบใใใใใงใฏใชใใ.
Place forward references (ใๅพใฎ็ซ ใงๆฑใใ) where the argument has settled (paragraph or section end), not mid-argument.
Do not mechanically convert speculation, possibility, reader-doubt, or counterfactual into assertion.ใใใใใใชใใใใ ใใใใใใใ ใใใใใใare removed only when they weaken a claim without grounds; keep the uncertainty when they express unconfirmed possibility, a character's perception, log-based inference, a doubt the reader might hold, or a counterfactual. Convert to assertion only when the proposition is settled by in-text grounds.
ๆ็คบใ็ถใใฆใใใใใใใชใ โ ๆ็คบใ็ถใใฆใใ
ๆ็คบใ็ถใใฆใใๅฏ่ฝๆงใใใ
Do not lump distinct things as "the same".
ไธใคใฎไบใใซไพๅญใใๆชๆฑบๅฎใฎๆฑบๅฎใใๅใๆฑบๅฎใๅฅใ
ใซไธใใฆใใใใจๆธใ
ใฉใใๅฅใ
ใฎๆฑบๅฎใงใใใใใใไบใใซไพๅญใใฆใใ
Do not reduce a multi-factor event to a single cause; if an example contains multiple kinds of problems, separate them and map which tool explains which.
ๅฅ็ดใฎๆฌ ๅฆใจๆ
ๅ ฑ้ ่ฝใฎๅคฑๆใๆททๅจใใไบ่ฑกใไธๆฌใใฆใๆ
ๅ ฑ้ ่ฝใฎๅ้กใใจ่ชฌๆใใ
Keep treatment of the same concept consistent across chapters and sections (do not classify something asใไบบ้ใๆฑบใใใin one section andใใใผใ ใงๅๆใใใin another). Classification, definition, and term status must be uniform throughout.
When asserting causation, state the mechanism in one sentence; do not writeใAใ ใจBใซใชใใand omit the reason.
ๆ้ ใงๅใใใจๅคๆดใๅ
จไฝใซๆณขๅใใ
ๅๅทฅ็จใใใผใฟใๅใๆธกใใใใฎ่กจ็พใๅ
ฑๆใใฆใใพใใใใฎ่กจ็พใๅคใใใจๅ
จไฝใซๆณขๅใใ
Do not write detection, guarantee, or resolution as if always achievable; state conditionally and precisely (ใใใใใใใใใใงใใใใจใๅคใใใใใๆใ็ซใคใจใใซ้ใใ).
Verify the given example actually supports the whole claim; if it supports only part, narrow the claim to match the example.
A point deferred forward withใๆฌก็ฏใงๆฑใใmust actually be paid off there; do not plant foreshadowing you never collect.
After a concession or limitation (ใใใ ใใใใจใฏใใใ), always advance the argument; do not end on the adversative and leave it hanging.
A section's central term must have its definition or scope stated before use within or before that section; do not start using it undefined.
When merging several concepts under one umbrella term, state in one sentence just before naming that they reduce to the same thing; also bridge the reverse (decomposition) operation.
Do not introduce proper nouns (file names, function names, identifiers) that are not referenced later; use general phrasing likeใไปๆงๆธใใ้้ก่จ็ฎใฎใฆใผใใฃใชใใฃใ.
When an abstract phrase's referent is not uniquely determined by context, pin it down in place with a parenthetical apposition so the reader need not look back.
When adding a new example or scene increases the context the reader must hold, preface it with what differs from the prior example and why another is needed.
In chapter and section intros, do not pack excessive detail unrelated to the example to come.
Even within an example section, omit only the detail unrelated to that section's question or consequence; keep concretes needed for the argument. Typical omissions: decorative precision of agent reports (timestamps, HTTP status, coverage %), and proper nouns not referenced later.
In examples, write an actor-as-subject chain of actions (ใใชใใธใใชใ่ชฟๆปใใฆ็นๅฎใใ่ฆใคใใฆใใใใ), not a list of results or passive voice (ใ็นๅฎใใใๅคๆใใใ).
Do not gratuitously prefix fictional personas likeใๅ
ฅ็คพ2ๅนด็ฎใฎใจใณใธใใขใใ.
In argument, do not call the readerใใใชใใ; use a role name (ใ้็บ่
ใใ่ชญ่
ใ). Reserve second-person address for limited spots (scene setupใใใจใใใใ, chapter or book closings).
Choose concrete referents; do not blur with broad words likeใAIใใใใผใซใ.
Once you introduce a formalization or term (K, ๅฅ็ด, ไธๅคๆกไปถ, etc.), keep using that word; do not regress to vague words likeใๆ่ใใใใผใซใใAIใ(usingใๆ่ใas a pre-formalization introductory word is fine).
Choose the conventional term in the field for a translation or technical term (push notification isใ้
ไฟกใnotใ้
้ใ); do not assign a near-synonym Kanji word by general feel.
Refer to people themselves in the original spelling (Lehman, Bainbridge). But for historical figures or eponymous concepts introduced by their settled name, use the katakana nickname current in Japanese.
Do not repurpose a term-sounding word into a non-term context (calling the chain from system to human aใ็ต่ทฏใ). Use ordinary phrasing likeใๅฑใใพใงใฎๆตใใใใใใ ใซไฝใใใใใ.
This is restraint, not a total ban; use rhetoric only where it works.
Use suspense (ใใใใซใฏใใๆฝใใงใใใ) or rhetorical questions to dramatize a derivation only where the tension aids the argument; where explanation suffices, just state it.
Do not overuse the device of isolating a short punchline into its own paragraph for tension. A short ไฝ่จๆญขใ within a paragraph (ใใใใพใงใใใๆฐๅ็งใใ) is allowed only at a climax.
Do not overuse bold in body text; limit to logical crux points (misreading-preventing negations, section conclusions), one or two per section, intro allowed. Otherwise let sentence order and structure do the emphasizing.
Prefer the worker-judgment form (ใใใใใใใซใฏใใใชใใ) over the imperative assertion (ใใใใฆใฏใชใใชใใ).
Do not over-dramatize turning points; one factual sentence usually suffices. Only at an argument's climax, a short sentence with an exclamation mark is tolerable.
Do not stoke fear of accidents or danger by enumerating consequences.
Do not pre-announce a claim withใ้่ฆใชใฎใฏใใงใใใ; just state the claim. (A preface declaring the claim's form, likeใๆจ่ชใจใใฆ่จใๆใใใฐใ, is fine.)
Do not overuse the antithetical punchlineใAใงใฏใชใBใ ใฃใใ. Light supplements or evaluations may be added in parentheses.
Do not use twisted idioms (ใ็ฅ่ญใไฝใซๅ
ฅใใใ) or metaphors whose referent is not uniquely determined (ใๅ ฑๅใฎๅคๅดใซไธ็ใๅบใใฃใฆใใใ); say it plainly with simple verbs (ใ่บซใซใคใใใๆฐไปใๆฉไผใๆธใใ).
High value; after drafting, self-check against this. Using the book's own terms in argument is fine; the problem is empty decoration. Japanese phrase tokens are kept verbatim.
Avoid announcement and summary padding:ใ้่ฆใชใฎใฏใใงใใใใๆฌ็ซ ใงใฏใใๆฑใ๏ผๆขๆฑใใใใใใใงใฏใใซใคใใฆ่ฆใฆใใใใใพใจใใใจใใ่ฆใใใซใ(when only restating the prior line),ใใใซไปใชใใชใใ.
Avoid theใๆญฃ้ขใใใfamily:ใๆญฃ้ขใใๆฑใใใๆญฃ้ขใใๅๅใใใใๆญฃ้ขใใ่ฆใ๏ผๆธใ๏ผ็ซใฆใใโ they declare stance instead of content.
Avoid empty adjectives:ใไธๅฏๆฌ ใใๆ ธๅฟ็ใใ้ตใจใชใใใๆ นๆฌ็ใชใ(emphasis without explaining the claim),ใๅค่ง็ใใๅ
ๆฌ็ใใ็ทๅ็ใ(without saying what was examined how).
Avoid empty verbs:ใๆใไธใใใใๆทฑๆใใใใใ่จ่ชๅใใใ(ends without showing what was written how),ใ่งฆใใใใ่จๅใใใ(one-paragraph brush-off).
Avoid connective templates:ใใใซใใใฆใใใใจใใๅด้ขใใใใใใฎ่ฆณ็นใใใ(no new info),ใใใใซใใใพใใใๅ ใใฆใin a row.
Avoid weak hedges and praise:ใใใจ่จใใใ ใใใใใใใใใใชใใ(only when weakening a claim groundlessly; keep for speculation, hypothesis, reader-doubt, or character-perception),ใ้ๅธธใซใใๆฅตใใฆใใๅคงใใซใ(empty intensifiers).
Self-check examples:
ๆฌ็ซ ใงใฏใใใใฎ็่ซใๆญฃ้ขใใๆฑใ
ๆฌ็ซ ใงใฏใใใใฎ็่ซใๆฑใ
ๅค่ง็ใซๅๆใใใจใ้่ฆใชใฎใฏใใงใใ
่ฉไพกใฎๆ ธๅฟใฏใๆญฃใใใ่ชฐใ็ฅใฃใฆใใใใซใใ
Do not restate the same claim in paraphrase; write each claim once.
If adjacent sections state the same thing from different angles, their roles overlap; absorb one into the other into a single section.
Do not re-summarize a scene right after depicting it; leave only a single interpretive sentence (ใใใฎใใใชไฝๆฅญใฏใใปใผๅฎๅ
จใซไปปใใใใใ).
Combine parallel facts with the same logical role into one sentence; mark their logical status with the lead word (ใๅฝ็ถใ็ต็้จใฎๆๆฌกๅฆ็ใ้กงๅฎขใฎๆฏๆใใใใ).
Do not write intermediate steps the reader can supply.
If a multi-sentence argument compresses to one sentence, keep only the one;ใ่ฆใใใซใis allowed as a compression signal.
Do not add sentences that exist only for connection or evaluation (ใใใ่ชไฝใฏใใใใจใงใใใ).
Do not use imagined reader Q&A as rhetoric (posing a question and answering in one word); state the claim directly. Also avoid acting out the reader's reaction (ใใใจๆใใใใใใใชใใใใฎใจใใใงใใใ); make concessions plainly in the body (ใใใกใใใๅฆ็ฝฎใใฎใใฎใฏ้็บ่
ใๆฑบใใๅ้กใงใฏใชใใ).
Do not frame a likely reader idea with meta scaffolding (ใใใใพใงใฎ่ฉฑใซใฏ่ช็ถใช็ถใใใใใใใใจใใ็บๆณใงใใใ); write the idea directly. A reader's question may stay as a question (ใใใฎไฟๅฎใไปปใใใฐใใใฎใงใฏใชใใ ใใใใ).
Do not write author-stance disclaimers (ใๆฌๆธใใใใๅฆๅฎใใชใใ); state only the fact (ใใใซๆธใใใๅ ดๅใๅคใใ).
Make prose share context with the reader in the fewest steps; if it lands without unrolling every step, name the structure and assert it.
Do not preemptively bring out concepts or document names not yet introduced in the body.
Do not settle for weak hesitant predicates (ใๆๅนใชๅฏพ็ญใงใใใ); state what is settled by in-text grounds strongly and concretely (ใๆดป็จใซใใใฆๅฟ
้ ใงใใใ). Keep weak predicates that express genuine uncertainty, possibility, hypothesis, or reader-doubt; intentional softening for tone (ใๅฟ
้ ใ ใจ่จใฃใฆใใใใ) is allowed.
Connectives that set rhythm (ใใใใไธๆนใงใ) are not counted as redundancy.
Make headings specific enough to identify content: the question the section answers, or the object it treats.
Do not use procedure-only headings (ใไพใซๆปใใใใใ่ชญใฟ็ดใใ) or information-free headings.
Do not make a heading a "punchline" that states the section's conclusion (avoid spoiling the payoff at the heading).
A noun phrase naming the section's object is acceptable.
Whether interrogative or declarative does not matter; what matters is that it points to the object or the reader's question. Choose whichever suits the body's tone.
If an example may look contrived, do not hide it; pre-empt the reader's doubt and add brief grounds that it is realistically plausible.
Ground it not in the author's assertion (ใๅๅใใๅพใ็ถๆณใ ใ) but in a general fact or common view the reader can recognize from experience (ใใใฎ็็ถใฏ็ใใใชใใ ใใใใใใจใใ่จใๆนใใใ่ณใซใใใ).
Do not smoothly write unconfirmed things as if confirmed.
Adapt style to each language's conventions (not literal translation)
Keep technical terms consistent
Adjust examples for cultural relevance when appropriate
- Type: [tutorial/concept/comparison/case_study/opinion]
- Audience: [beginner/intermediate/advanced developers]
- Core message: [one sentence]
- Language: [en/ja/both]
- Target length: [word count]
[Section headings with key points]
[Article content]
- [ ] Hook is compelling
- [ ] Each section has one clear purpose
- [ ] Code examples tested and working
- [ ] Technical claims verified
- [ ] Read aloud for flow
- [ ] Trimmed unnecessary words
- [ ] Title and headings optimized
<title_patterns>
How to [achieve result] with [tool/technique]
How to Implement Rate Limiting with Redis
[N] [Things] Every Developer Should Know About [Topic]
5 Things Every Developer Should Know About TypeScript Generics
[A] vs [B]: Which Should You Choose in [Year]?
REST vs GraphQL: Which Should You Choose in [Current Year]?
Solving [Problem] with [Solution]
Solving N+1 Queries with DataLoader
Understanding [Concept]: A Deep Dive
Understanding React Reconciliation: A Deep Dive
What I Learned [Building/Using] [Thing]
What I Learned Building a Real-Time Collaboration System
</title_patterns>
<long_form_structure>
Patterns for book chapters, multi-part series, and other long-form pieces where the reader progresses across many sections. These operate above the single-article patterns and are language-neutral; when writing Japanese, also apply the japanese/prose_norms ruleset. They govern how a chapter opens, how examples grow, and how a chapter or a whole work closes.
Shape each chapter or installment as problem-then-solution
Introduction: make the conventional approach's failure concrete before naming the new approach. Show the scenario where the old method breaks (a realistic "works on my machine" or "the build fails on the new OS" situation) so the solution is felt as relief rather than asserted as superior.
Foundation: the core structure or theory of the new approach.
Migration: how to move from the old approach to the new one, shown as a side-by-side change of one concrete example.
Practice: a worked, realistic example.
Deep dive: the mechanism behind why it works.
Outlook: a bridge to the next chapter's higher demand.
Introduce the solution in three graded moves: what visibly changes ("it becomes this"), why it changes (the mechanism), then the essential value ("so, in effect"). Build credibility with one concrete, checkable fact (adoption status, a count of supported items, who authored it) rather than adjectives.
Keep the introduction's problem framing tight (roughly 300-400 words); a longer intro delays the payoff and front-loads detail unrelated to the example to come.
Grow code examples in stages rather than presenting one large block
Minimal example: the smallest version that runs.
Incremental complexity: add one axis at a time (an environment variable, then a hook, then a service), each as its own step.
Integrated example: combine the pieces into one realistic configuration.
Cap a single code block at what a reader can absorb in a few minutes (on the order of 50-70 lines); split anything longer.
Frame each block: one or two sentences of lead-in before it, a two- or three-sentence takeaway after it, and defer the deeper "why" to the following subsection.
Watch the prose-to-code balance. A section that is mostly code with thin narration is under-explained; when code exceeds roughly two-thirds of a section, add explanation or move some code to a later stage.
Trim decorative shell or log output to the few lines that carry the point (a 40-line status dump where 5-10 lines matter is noise).
Do not let example difficulty regress: the last example in a chapter should not be the simplest one.
Evaluate and write closing sections (chapter endings and the final chapter)
Name the specific technical elements the chapter taught, not a vague gesture at "what we covered".
State what was achieved and which problem it solved.
Point to concrete next actions and, at most, the single most important learning resource.
Ends by handing off to the next chapter's demand ("the environment built here now faces a higher requirement"). The default for interior chapters.
Ends a series by integrating all prior chapters. It must still name the individual results, not only assert a "culmination".
A closing section is short (about half a page, ~600 words across 3-4 paragraphs). Under-length is as much a defect as over-length: a final chapter that claims to integrate everything but omits the individual results is incomplete.
Does it reference the chapter's actual sections and results, not just its title?
Is there a single message focus rather than several competing ones?
Is the ending type (bridging vs terminal) consistent with sibling chapters' endings?
Reduce the bloat that accumulates across a long piece
Merge duplicated messages: the same claim restated in three places (a feature's "everything is automated" line appearing across three consecutive subsections) collapses to one.
Prune URL enumeration: cite the single most important link, not a list.
Cut encouragement padding ("surely", "you should be able to ...") and re-summaries that immediately follow the thing they summarize.
Define a central term before or at its first use within a section, and keep its meaning stable across chapters instead of reintroducing it with a shifted sense.
<best_practices>
Start with a compelling hook in the first paragraph
Use a problem the reader faces, a surprising fact, or a brief relatable story
Put the most important point first using inverted pyramid structure
Lead with the conclusion, provide TL;DR for long articles
Test all code examples before publishing
Verify code compiles, runs, and produces expected output
Explain code context before or after each snippet
Describe what the code does and why it's written that way
Support claims with evidence
Include benchmarks, examples, or reasoned arguments for technical claims
Each section should have one clear purpose
Split sections covering multiple ideas, use headings that summarize the key point
Use diagrams for architectural concepts
Include visual representations to complement text explanations
Vary sentence length for readability
Mix short and medium sentences to maintain reader engagement
Adapt style to language conventions
Use conversational but professional tone in English, ใงใใปใพใ่ชฟ in Japanese technical articles
For long-form pieces, frame the conventional approach's failure before introducing the solution, and escalate code examples from minimal to integrated
See long_form_structure: chapter_arc and code_example_escalation
</best_practices>
<anti_patterns>
Hiding the main point deep in the article
Put the most important point first, use inverted pyramid structure
Not explaining why the topic matters
Explain why the reader should care early in the article
Showing code without explaining its purpose
Explain what code does and why before or after the snippet
Making claims like "X is the best" without evidence
Support claims with benchmarks, examples, or reasoned arguments
Title promises more than content delivers
Ensure title accurately reflects content and scope
Long code blocks without explanation
Break up code with explanations, highlight key lines, add comments
Starting with "In this article..." or similar phrases
Start with a hook that captures attention immediately
</anti_patterns>
Test all code examples compile and run before publishing
Verify all technical claims with sources or benchmarks
Start with a compelling hook, never generic openings like "In this article..."
Explain code context before or after each snippet
Use inverted pyramid: most important point first
Break long code blocks with explanations
Ensure title accurately reflects content scope
Identify article type, target audience, and core message
Research topic using Context7 and WebSearch for accuracy
Create outline following the appropriate pattern structure
Write the hook and introduction first
Draft each section following one-idea-per-section principle
Add code examples, diagrams, and supporting evidence
Verify all code examples compile and run
Check technical claims against sources
Review against edit checklist
Read aloud for flow and trim unnecessary words
<error_escalation inherits="core-patterns#error_escalation">
Grammar or style issue
Technical inaccuracy in example
Misleading or incorrect technical claim
Content could cause harm if followed
</error_escalation>
Verify all technical claims
Test all code examples
Write for target audience level
Jargon without explanation
Untested code examples
Overly complex explanations
<related_skills>
Symbol operations for extracting code examples from projects
Library documentation lookup for accurate technical references
Researching technical topics and verifying claims
Creating reference documentation from blog content
</related_skills>
<related_agents>
Primary agent for technical article and blog post generation
Review technical writing for clarity, accuracy, and structure
</related_agents>
