Build Protocol

turn "write a knowledge product" into a rigorous 9-step workflow with machine-verifiable quality gates. distilled from 4 battle-tested projects: a multi-chapter AI/ML textbook, a tactical gear knowledge base, a supplements knowledge base, and a product design doc series.

intent

use this skill when you're building long-form knowledge products that will live in production and be referenced repeatedly. applies to textbooks, knowledge bases, deep technical reports, and reference materials. the protocol enforces 8 non-negotiable rules (independent audit, plan before execute, sub-agent caps, explicit reasoning, versioning, consistency layers, anti-sycophancy metrics, and cross-agent review) plus a 9-step standard workflow with machine-verified quality gates. triggers on explicit requests ("build knowledge base", "write textbook") or implicitly whenever output will exceed 5,000 words, require more than 2 sub-agents working in parallel, or need >10 execution steps. skip this for one-off Q&A, simple docs, or short reports under 5k words.

inputs

required context and parameters:

• task description (goals, scope, target audience, success criteria)
• estimated output size in words
• number of parallel sub-agents needed
• whether deliverable will be long-term reference material (yes/no)
• target publication format (markdown, docx, html, pdf)

external connections and setup:

• file storage system (local filesystem, s3, sharepoint, google drive) , specify root folder path and permissions
• document versioning system (git, version-control folder, or archive strategy) , version numbering scheme and history location
• citation backend (if applicable: pubmed/pmid lookup, arxiv, doi resolver, or manual citation list) , api keys or connection strings as env vars
• sub-agent dispatch system (bedrock, openai batch api, or custom harness) , region, model tier, timeout settings

machine verification scripts (provided in references/):

• audit_check.sh , bash script for citation, length, safety keyword, h1 count, and red/green ratio checks
• grep and sort | uniq -c , built-in commands for deduplication and coverage analysis
• domain-specific validators (e.g., pmid format checker for medical content) , pre-staged in references/

edge cases and dependencies:

• api rate limits and throttling on sub-agent dispatch , jitter second sub-agent start by 1-3 seconds, use different bedrock regions if available
• auth expiry on external citation services , refresh tokens before audit step, fall back to manual citation if service unavailable
• concurrent file access contention , serialize file moves and uploads, max 2 parallel file operations at a time
• context window limits on audit agents , reduce scope to l1 + l4 only if context >85%, defer l5/l6 to next version
• timeout cascades when dispatching >2 sub-agents to same region , use batching strategy (2+2+1) instead of 5+ parallel

procedure

step 1: plan

• input: task description, scope, audience, deliverable format
• create detailed outline with section breakdown, target word count per section, estimated sub-agent allocation
• identify sub-agents needed (max 2 in parallel for writing tasks; non-writing tasks can go up to 4)
• estimate total time, including audit and fix cycles
• output: plan document (markdown or text) with outline, sub-agent task list, and timeline

step 2: prepare

• input: plan document from step 1, source material or references
• extract and chunk content into sub-agent tasks; each task instruction ≤3,000 chars (just-in-time context principle)
• create sub-agent spec for each task: goal (one sentence), output file path and format, content (direct key info), constraints (what not to do), acceptance criteria (measurable completion)
• stage all source material and reference files in a shared folder with clear folder structure
• output: sub-agent task specs (one per file, stored in prep/ folder), staging folder with indexed references

step 3: execute

• input: sub-agent task specs from step 2, access to sub-agent dispatch system
• dispatch first sub-agent with full task spec and staged references
• wait 1-3 seconds (jitter), then dispatch second sub-agent if applicable, to different region if available
• do not dispatch more than 2 sub-agents in parallel for writing tasks; if >2 needed, batch as (2 parallel) → wait → (2 parallel) → wait → (1 final)
• monitor for timeouts, throttling, or auth failures; retry failed tasks with different model or region
• output: sub-agent outputs (raw markdown, docx, or text files) in execute/ folder, timestamped

step 4: assemble

• input: sub-agent outputs from step 3
• merge outputs into single file, preserving original order from outline
• unify formatting (heading levels, code block syntax, link format, reference style)
• grep and remove sub-agent progress markers (e.g., # progress: step X/N, [sub-agent working...]) before audit
• check for obvious duplicates or conflicting sections; flag for manual review if >1 section covers same topic
• output: assembled knowledge product file (e.g., assembled.md), cleaned of metadata, stored in assemble/ folder

step 5: review (lightweight)

• input: assembled file from step 4
• scan for formatting consistency (h1 count exactly 1, heading hierarchy, code block formatting, link validity)
• check for incomplete sections, missing citations, or orphaned references
• verify output file matches intended format (markdown, docx, etc.)
• flag dirty markers or editorial notes for removal
• output: review checklist with pass/fail status for each criterion, minor corrections applied

step 6: audit (deep, independent, unmissable)

• input: assembled file from step 5, audit requirements (citation threshold, safety keyword list, red/green ratio target)
• dispatch independent audit agent (not the writer agent, not the main agent if it wrote content) with deliverable only, no original requirements context
• run audit_check.sh (or equivalent) to machine-verify:
  • l1.1 citation count: ≥threshold (e.g., ≥5 pmids for medical, ≥3 for general reference)
  • l1.2 citation duplicates: zero duplicates (sort | uniq -c | awk '$1>1' returns empty)
  • l3 length: each major section ≥6,000 chars
  • l3 gender balance: male and female perspectives both present (if applicable to domain)
  • l4 safety coverage: ≥3 safety keywords per major section (for health/medical/safety content)
  • l5 h1 count: exactly 1 h1 per file (no stray h1s from sub-agent progress markers)
  • l6 red count: ≥1 red (🔴) critical review per major section; ideally red ≥20% of green count (grep -c "🔴" / grep -c "🟢")
• audit agent produces issue report with severity (🔴 blocker, 🟡 defer-able, 🟢 nice-to-have)
• output: audit report (markdown) with issue list, severity tags, evidence, stored in audit/ folder

step 7: fix (priority-ordered)

• input: audit report from step 6, assembled file from step 5
• fix all 🔴 blockers first: rewrite sections, add missing citations, add safety content, add anti-sycophancy negatives (red flags, caveats, limitations)
• fix all 🟡 improvements second: reword unclear passages, add examples, improve structure
• defer all 🟢 cosmetics to next version; log them in changelog
• after each fix, re-run audit_check.sh (or equivalent) to verify no new duplicates or regressions introduced
• output: fixed knowledge product file, updated audit report showing resolved issues, stored in fix/ folder

step 8: publish

• input: fixed file from step 7, audit report showing all 🔴 resolved
• convert to target format (docx, pdf, html, or keep as markdown)
• upload to target location (folder path, s3 bucket, sharepoint, google drive); use 3-step upload procedure if moving to subfolder: (1) upload to root, (2) move to folder, (3) verify presence
• do not parallelize file moves >2 at once; serialize if >2 files being moved
• generate citation metadata (e.g., doi, version tag)
• output: published file at target location, verifiable via url or path, version tag applied

step 9: errata (ongoing)

• input: post-publication feedback, issues found after release
• categorize new issues as 🔴 (blocker for v1.1), 🟡 (improve for v1.2), or 🟢 (defer)
• for each fix, create changelog entry: v1.1 · YYYY-MM-DD: 🔴 Fixed [blocker], 🟡 Added [improvement], 🟢 Deferred [minor]
• increment version: +0.1 for ≤3 small fixes per ~5k words, +1.0 for ≥50k words added or ≥3 new chapters
• archive old version to HistoryBackup/; publish new version
• output: versioned file with changelog, history folder updated

decision points

if sub-agent times out on first dispatch: retry with different model tier (e.g., opus instead of sonnet) or different region (us-east instead of eu-west). if 3+ models all timeout, main agent audits manually using grep scripts and direct review (main agent has stronger model and can use machine checks).

**if audit agent fails or produces low-quality audit (<10 real issues found):** dispatch second independent audit agent for cross-validation. if time-pressed and context window >85%, reduce scope to l1 + l4 only; skip l5/l6 and defer to next version.

if assembled file has >1 section covering the same topic: flag for manual review; choose strongest version, merge unique content, mark conflict as editorial decision in changelog.

if citation backend (pubmed, arxiv, doi) is unavailable during audit: fall back to manual citation format check (grep for pmid pattern, verify doi syntax); note unavailability in audit report. do not publish if l1.1 citations cannot be verified; retry audit step next day.

if fix step introduces new issues (e.g., duplicate citations after rewrite): re-run audit_check.sh immediately after each fix. do not skip verify-after-fix step. if new issues found, iterate step 7 again.

if concurrent sub-agent dispatch causes throttling (timeout on second agent): jitter second sub-agent start by 1-3 seconds. if still throttled, use different bedrock region for second agent. if same-region only, batch as (2 parallel) → wait 5 min → (2 parallel) instead of 4 parallel.

if upload/move hits resource contention: retry individually (one file at a time); do not parallelize >2 file operations. use exponential backoff: retry after 2s, then 5s, then 10s.

if docx upload loses folder_token parameter: use 3-step procedure: (1) upload to root destination, (2) move file to target folder, (3) verify file present at target path before considering step 8 complete.

if red/green ratio fails (all 🟢, zero 🔴): this is a blocker; the content is fake or incomplete. audit agent must add explicit negatives, caveats, or limitations to achieve 🔴 ≥20% of 🟢 count. do not publish all-green content.

if deliverable will be short-form (< 5,000 words) or non-referential (one-off Q&A): do not use this skill; use a simpler single-agent prompt instead. this skill is overkill for short, ephemeral content.

output contract

delivered file(s):

• primary deliverable: single markdown or docx file, version-tagged (v1.0, v1.1, etc.), stored at agreed location (folder path, s3 url, sharepoint link)
• changelog: markdown file named CHANGELOG.md or RELEASE_NOTES.md, listing all versions with 🔴/🟡/🟢 categorized fixes
• audit report: markdown file in audit/ folder showing all machine-verified metrics (citation count, length, safety keyword coverage, red/green ratio) and final pass/fail status per criterion
• history archive: HistoryBackup/ folder containing all previous versions (v1.0, v1.0.1, etc.) with timestamps

data format and structure:

• markdown files: utf-8, no smart quotes, consistent heading hierarchy (exactly 1 h1, multiple h2s, optional h3s)
• docx files: styles applied (heading 1, heading 2, normal), no embedded fonts, hyperlinks preserved
• citations: inline (markdown link or footnote) or separate reference list, consistent format per domain
• metadata: version string in filename and file frontmatter (e.g., ---\nversion: 1.0.1\npublished: 2026-04-29\n---)

quality gates (all must pass before step 8 publish):

• all 🔴 issues from audit resolved (zero blockers remaining)
• l1.1 citation count ≥ threshold (domain-specific minimum)
• l1.2 zero duplicate citations (uniq -c returns 0 duplicates)
• l3 length ≥ 6,000 chars per major section
• l4 ≥ 3 safety keywords per major section (if applicable)
• l5 exactly 1 h1 per file
• l6 🔴 ≥ 20% of 🟢 count (e.g., if 100 green checkmarks, ≥20 red flags)
• no sub-agent progress markers in final file
• formatting consistent (headings, code blocks, links, references)

outcome signal

you know the skill worked when:

• published file is accessible at target location (url, folder path, or share link confirms visibility)
• version tag appears in filename and frontmatter (v1.0.1)
• changelog exists and lists all fixes applied with 🔴/🟡/🟢 categorization
• audit report shows all machine-verified metrics passing (citation count, zero duplicates, length, safety coverage, red/green ratio)
• zero 🔴 blockers remaining (audit report shows only 🟡 deferred or 🟢 cosmetics)
• user can cite the deliverable by version and date (e.g., "v1.0.1 published 2026-04-29")
• if user finds issues post-publication, they can file them against a specific version and expect an errata cycle (v1.1) within defined timeline
• independent audit agent (not writer, not main agent) produced the final audit report, confirming non-sycophantic review
• content includes explicit negatives or caveats (🔴 markers visible), not all-positive claims

---

distilled: 2026-04-29 · source: BUILD-PROTOCOL.md v1.1 (refined through dogfood) validated on: AI/ML textbook, tactical gear KB, supplements KB (v1.0 → v1.1 dogfood)