dk-wiki-article-writing

name: dk-wiki-article-writing description: Use when writing a Wikipedia-style article or comprehensive research-backed document on a technical topic. Produces balanced, well-sourced articles with proper citations by researching from multiple angles before writing. compatibility: "Python 3.10+ with uv. BRAVE_API_KEY env var for web search (ddgr used as primary, Brave API as fallback)." allowed-tools: bash, read, write, edit, subagent license: MIT metadata: author: dushyantkhosla version: "2.0" requires: "uv" optional: "BRAVE_API_KEY for web search"

Wiki Article Writing

A research-first workflow for writing comprehensive, balanced, Wikipedia-style articles on technical topics. The core principle: research breadth before writing depth — never start writing until you've heard from voices you didn't expect to find.

Overview

This skill enforces a 6-phase pipeline that prevents the most common failure mode in AI-assisted article writing: advocacy bias from narrow sourcing. When you only search for the names you already know, you get a highlight reel, not an encyclopedia.

Research is parallelised via subagents — multiple research threads run concurrently, each writing findings to files. Synthesis happens only after all threads complete.

When to Use

• Writing a Wikipedia-style article on a technical topic
• Creating a comprehensive research document that needs balanced coverage
• Producing an HTML page displaying a well-sourced article
• Any task requiring multi-source research synthesis before writing

When NOT to Use

• Quick summaries or opinion pieces (no balance needed)
• Internal documentation (no citation requirements)
• Topics with no existing discourse (nothing to balance against)

Phase 0: Research Plan

Goal: Define what to research before searching. This prevents reactive, unfocused searching.

1. Create the research folder:

mkdir -p research_{topic_slug}

2. Write research_{topic_slug}/research_plan.md containing:

# Research Plan: {Topic}

## Main Research Question
{What is this article about?}

## Subtopics (3-5, non-overlapping)

### Subtopic 1: {name}
- **Search angles:** {2-3 specific queries}
- **Expected sources:** {what kind of blogs, docs, discussions}
- **Budget:** 3-5 searches max

### Subtopic 2: {name}
- **Search angles:** {2-3 specific queries}
- **Expected sources:** {what kind of blogs, docs, discussions}
- **Budget:** 3-5 searches max

### Subtopic 3: {name}
...

## Synthesis Approach
How will findings combine into a balanced article?

Subtopic sizing guide:

Save to: research_{topic_slug}/research_plan.md

Phase 1: Wikipedia Baseline

Goal: Understand what already exists and mine references.

Fetch the Wikipedia article:

uv run {baseDir}/scripts/wiki.py "YOUR_TOPIC_HERE" --full --refs --toc

uv run auto-installs pywikibot on first run. Outputs article text, reference URLs, and TOC links.

Note gaps: What's missing? What's underdeveloped? What's the tone?

Save to: research_{topic_slug}/wikipedia-baseline.md

Phase 2: Parallel Research (Subagents)

Goal: Find voices across the full spectrum — proponents, critics, practitioners, independent observers — efficiently via parallel delegation.

Delegation Strategy

For each subtopic in your research plan, spawn a research subagent. Run up to 3 in parallel.

Subagent task template:

Research "{SUBTOPIC_NAME}" for a Wikipedia-style article about {TOPIC}.

Search angles:
- {query_1}
- {query_2}
- {query_3}

Use the search tool:
  {baseDir}/scripts/search.sh "{query}" 10

For the 2-3 most important results, fetch full content:
  {baseDir}/scripts/search.py "{url}" -n 1 --content

Write your findings to research_{topic_slug}/findings_{subtopic_slug}.md with:
- Key claims and arguments (with attribution)
- Notable quotes (exact text)
- Source URLs
- Stance (pro/con/neutral/nuanced)
- What this source ignores or assumes

Budget: 3-5 searches maximum. Stop when you have enough for a balanced view.

What to Record Per Finding

• Title and URL
• Source type: official blog, practitioner blog, news, forum, academic, docs
• Stance: pro, con, neutral, nuanced
• Key claim (one sentence)
• Notable quote (exact text, with attribution)

Rate Limit Handling

If search.sh returns errors, wait 3-5 seconds between calls. The script auto-falls back from ddgr to Brave API.

Save each subagent's output to: research_{topic_slug}/findings_{subtopic_slug}.md

Phase 3: Deep Dive

Goal: Read the most important sources in full. Search snippets lie; full text reveals nuance.

Priority Order

1. Criticism pieces — hardest to find, most valuable for balance
2. Practitioner experience reports — real-world workflow details
3. Official documentation from tool vendors
4. Community discussions (HN threads, Reddit)

Fetching Content

uv run {baseDir}/scripts/search.py "https://example.com/article" -n 1 --content

What to Extract

From each article, capture:

• Author's main argument (2-3 sentences)
• Key evidence or data points
• Notable quotes (exact text, with attribution)
• What they're responding to (context of the debate)
• Blind spots (what they ignore or assume)

Save to: research_{topic_slug}/deep-dives.md

Phase 4: Source Audit & Gap Analysis

Goal: Verify balanced coverage before writing. This is the phase most workflows skip.

The Balance Checklist

Read all files in research_{topic_slug}/. Ask yourself:

• Do I have at least 2 strong critical perspectives?
• Do I have independent voices (not just vendor blogs)?
• Do I have community sentiment (Reddit, HN, forums)?
• Do I have practitioner experience reports (not just theory)?
• Can I articulate the strongest argument against this topic?
• Do I know what opponents would say about my article?
• Am I including voices I didn't expect to find?

If any answer is "no", spawn one more targeted subagent to fill the gap.

Identify Missing Perspectives

• Who is missing? (geographic, institutional, methodological)
• What angle is underrepresented?
• What criticism have I not found?

Save to: research_{topic_slug}/source-audit.md

Phase 5: Write the Article

Goal: Produce a balanced, well-structured, Wikipedia-style article with proper citations.

Article Structure

# {Topic Name}

**{Topic Name}** is {one-paragraph bold definition}. {2-3 sentences of context}. {Why it matters now}.{superscript citations}

---

## Contents
1. [Overview](#overview)
2. [History and origins](#history-and-origins)
3. [Key proponents](#key-proponents)
4. [Comparison with other approaches](#comparison-with-other-approaches)
5. [How it works](#how-it-works)
6. [Tools and ecosystem](#tools-and-ecosystem)
7. [Practical benefits](#practical-benefits)
8. [Criticism and limitations](#criticism-and-limitations)
9. [See also](#see-also)
10. [References](#references)
11. [External links](#external-links)

---

## Overview
{Expanded definition, core concepts, why it matters}

## History and origins
{Chronological narrative with citations}

## Key proponents
{Subsections for major voices — not just the famous ones}

## Comparison with other approaches
{Table format — neutral, factual}

## How it works
{Numbered workflow steps}

## Tools and ecosystem
{What exists, with links}

## Practical benefits
{What proponents claim, cited}

## Criticism and limitations
{What critics say, cited — EQUAL weight to benefits}

## See also
{Related topics}

## References
{Footnote-style numbered citations with URLs}

## External links
{Key URLs}

Writing Rules

1. Neutral tone — "Proponents argue..." not "This is better because..."
2. Cite everything — use <sup>[N]</sup> footnote syntax
3. Give criticism equal weight — if benefits get 500 words, criticism gets 500 words
4. Include dissent — the strongest counterargument, not a straw man
5. No advocacy — encyclopedia entry, not blog post
6. Target 2,500–4,000 words for comprehensive coverage

HTML Generation (Optional)

If an HTML page is needed, create a self-contained file:

• Wikipedia-inspired design (serif body, sans-serif UI)
• Dark mode via prefers-color-scheme
• Responsive (max-width ~960px, mobile breakpoints)
• Styled comparison table with alternating rows
• Citation superscript links
• All CSS inline, zero external dependencies

See references/html-template.md for reusable CSS patterns.

File Organization

output-directory/
├── research_{topic_slug}/
│   ├── research_plan.md           # Phase 0
│   ├── wikipedia-baseline.md      # Phase 1
│   ├── findings_{subtopic}.md     # Phase 2 (one per subagent)
│   ├── findings_{subtopic}.md
│   ├── ...
│   ├── deep-dives.md              # Phase 3
│   └── source-audit.md            # Phase 4
├── {topic-name}.md                # Phase 5: The article
└── {topic-name}.html              # Phase 5: HTML page (optional)

Common Mistakes

Quality Checklist

Before delivering the article, verify:

• Research plan written before searching (Phase 0)
• 2,500+ words (comprehensive coverage)
• 10+ sections (all phases covered)
• 20+ citations (footnote-style with URLs)
• Comparison table (at least 3 related approaches)
• Criticism section (at least 400 words, with named sources)
• Independent voices (not just vendor blogs)
• Community sentiment (Reddit/HN/forum perspectives)
• Neutral tone (no advocacy language)
• HTML page renders correctly (if generated)