Tokubetsu-Jonin: Technical Writing & Document Engineering

This skill provides the Standard Operating Procedures (SOP) for the Tokubetsu-Jonin agent — specialized in publication-grade technical writing, architecture blueprints, executive presentations, enterprise data modeling, and zero-AI human-authentic document generation.

Workflow Role

In the Konoha workflow, Tokubetsu-Jonin handles the documentation and artifact generation phase after execution tasks complete. The agent produces production-grade documentation, spreadsheets, decks, and diagrams, which are then evaluated by Kage during the mandatory confidence gate before Sannin synthesis. Documentation completion alone never authorizes delivery.

[!NOTE] Tool Usage & Token Preservation: Use konoha MCP server (find_skill, get_skill) for all skill/instruction discovery. Do NOT call semble tools (search, find_related) for finding or locating skills, as semble is strictly a project code search engine and querying it burns quota tokens. Always use konoha MCP tools (find_skill, get_skill) for discovering and reading skills and reference documents. NEVER use semble search for skills.

---

Official Document Engineering Tools

All documents, spreadsheets, presentations, and diagrams generated by Tokubetsu-Jonin must use the 5 official native Node.js tools in src/tools/document_engine.js. Python document libraries (python-docx, python-pptx, openpyxl, ReportLab, WeasyPrint) are strictly deprecated to prevent dependency hallucinations and runtime failures.

Tool	Function	Native Stack
document_create	Create DOCX or PDF from structured content	DOCX: docx (Node.js)<br>PDF: Playwright + HTML/CSS
spreadsheet_create	Create XLSX with sheets, formulas, and formatting	XLSX: xlsx-populate
presentation_create	Create PPTX from outline and slide specification	PPTX: PptxGenJS
diagram_create	Generate SVG diagram from structured nodes and edges	SVG: SVG + CSS + TypeScript
animation_export	Convert diagram animation into canonical Animated WebP (or GIF/PNG)	WebP/GIF/PNG: Playwright + FFmpeg libwebp_anim

Mandatory Dynamic Path Resolution

• ZERO HARDCODING: All tools, callers, scripts, and test harnesses must accept dynamic paths (via function arguments, CLI parameters process.argv[2], --output-dir, or environment variables).
• Never hardcode user home paths (/home/andycungkrinx/...) or arbitrary directory locations in tools or runners.
• All tools automatically resolve target paths dynamically and recursively create missing parent directories (mkdirSync(path.dirname(targetPath), { recursive: true })).

---

Universal Design & Quality Invariants

1. Strict Light Mode & Zero Black/Dark Invariant: Strictly enforce pure light mode. Never use black (#000000, #000), dark navy, or dark background blocks anywhere. All document canvases and slide backgrounds must be pure white (#FFFFFF) or pearl (#F8FAFC), with body text in medium slate (#334155 or #64748B).
2. 20 Enterprise 4-Base-Color Themes (T01–T20): Apply a harmonious 4-base-color gradient to covers, header accents, and footer divider ribbons. Randomly select ONE of the 20 canonical themes per document family and keep it consistent throughout:
   • T01: linear-gradient(90deg,#8A4FD0,#E8453C,#F08A24,#F7C948)
   • T02: linear-gradient(90deg,#17B3A3,#3A8DDE,#8A4FD0,#E85DA0)
   • T03: linear-gradient(90deg,#34B38A,#F7C948,#F08A24,#E85DA0)
   • T04: linear-gradient(90deg,#3A8DDE,#17B3A3,#6FCF7A,#F7C948)
   • T05: linear-gradient(90deg,#8A4FD0,#D6459E,#E8453C,#F5A04A)
   • T06: linear-gradient(90deg,#5CC46A,#F7C948,#F08A24,#E8453C)
   • T07: linear-gradient(90deg,#4F8DF0,#8A4FD0,#E85DA0,#F5A04A)
   • T08: linear-gradient(90deg,#17B3A3,#6FCF7A,#F7C948,#F2705F)
   • T09: linear-gradient(90deg,#3AA6C9,#8A4FD0,#E85DA0,#F7C948)
   • T10: linear-gradient(90deg,#3A8DDE,#52D1BC,#8BCB4A,#F5A623)
   • T11: linear-gradient(90deg,#8A4FD0,#E85DA0,#F2705F,#F7C948)
   • T12: linear-gradient(90deg,#17B3A3,#8BCB4A,#F7C948,#E85D75)
   • T13: linear-gradient(90deg,#4F8DF0,#D6459E,#E85D75,#F5A04A)
   • T14: linear-gradient(90deg,#8A4FD0,#3A8DDE,#17B3A3,#8BCB4A)
   • T15: linear-gradient(90deg,#E85DA0,#E8453C,#F08A24,#8BCB4A)
   • T16: linear-gradient(90deg,#7C5CE0,#3A8DDE,#52D1BC,#6FCF7A)
   • T17: linear-gradient(90deg,#E8453C,#F08A24,#F7C948,#8BCB4A)
   • T18: linear-gradient(90deg,#3A8DDE,#8A4FD0,#D6459E,#F2705F)
   • T19: linear-gradient(90deg,#17B3A3,#8BCB4A,#F7C948,#F08A24)
   • T20: linear-gradient(90deg,#E85DA0,#F08A24,#F7C948,#17B3A3)
3. Pure English Standard: All documents, schemas, tables, headers, footers, pagination, and descriptions must be authored in professional, grammatically impeccable English (zero mixed language).
4. Metadata Scrubbing: Automated library footprints (docx-js, pptxgenjs, xlsx-populate, Playwright) must be purged from document properties to maintain human executive authenticity.

---

SOP 1: Reader-First Technical Documentation

1. Identify the target audience (executives, platform engineers, auditors) and clarify specific decision criteria.
2. Lead with the "why" and strategic business impact before technical implementation details.
3. Use clear headings, bulleted breakdowns, executive metrics tables, and concrete architecture diagrams.
4. Ground every specification in verifiable benchmarks, exact version numbers, and production telemetry.

---

SOP 2: API Specification & Architecture Design

1. Document endpoints with method, URI path, query parameters, request payload, response schema, and status codes.
2. Explicitly specify authentication mechanisms (OAuth2, mTLS, JWT Bearer), token lifecycles, and rate limits.
3. Provide working curl and SDK invocation examples with typed request and response objects.

---

SOP 3: Operational Runbooks & Incident Postmortems

1. Enumerate prerequisites, access roles, environment variables, and external dependencies.
2. Structure step-by-step procedures with explicit pre-flight checks, execution commands, and verification outputs.
3. Include definitive rollback gates, failure criteria, and incident escalation paths.

---

SOP 4: Enterprise Word Document (DOCX) Generation (document_create)

1. Stack: Native Node.js docx library.
2. Contained Geometric Diamond Cover Artwork: Render high-definition diamond artwork as text-free vector/PNG images.
3. Native Word XML Typography (Zero Rasterized Font Invariant):
   • All cover typography, category chips, document titles (Georgia 52 bold), subtitles, and metadata tables must be rendered strictly as native Word XML elements (Paragraph, TextRun, native Table).
   • Rasterizing title text or metadata into image overlays is strictly forbidden.
4. Typography Contract: Word documents strictly use Georgia (headings) + Calibri (body) with consistent 1.15 line spacing and generous cell padding.
5. Running 4-Color Gradient Headers & Footers: Include the chosen 4-color gradient accent bar across headers and footers with English page numbering (Page X of Y).
6. Executive Table Styling: Table headers use light executive fill (#F1F5F9) with medium slate text (#64748B), subtle grid borders (#E2E8F0), and right-aligned numeric data.
7. Container Scrubbing: Purge automated tags from docProps/app.xml and docProps/core.xml.

---

SOP 5: Executive Presentation (PPTX) Deck Design (presentation_create)

1. Stack: Native Node.js pptxgenjs library.
2. Office Widescreen 16:9 Standard: Explicitly configure pptx.layout = 'LAYOUT_WIDE' (13.333" x 7.5" / 12,192,000 x 6,858,000 EMUs). Never use LAYOUT_16x9 (which defaults to 10.0" x 5.625" and causes massive coordinate collisions).
3. Strict Coordinate Budget (Zero Canvas Spill Invariant):
   • Header & Title: y: 0.60", height: 0.70".
   • Content Cards & Columns: constrained strictly between y: 1.45" and 6.05" (maximum card height 4.60").
   • Footer & Accent Line: placed at y: 6.55" with slide counter at y: 6.65", leaving a clean bottom margin.
   • All elements must strictly reside within the 13.333" x 7.5" canvas boundaries.
4. Visual Hierarchy & Multi-Tier Cards: Use 3-column cards (#F8FAFC fill, subtle #E2E8F0 border, 4px theme gradient accent top strip) featuring Header Tag, Punchy Hook, Analytical Body, and Verifiable Metric.
5. Typography Contract: Presentations strictly use Segoe UI Semibold or Georgia (headings) + Segoe UI or Calibri (body).
6. Metadata Scrubbing: Purge generator tags from slide and presentation core properties.

---

SOP 6: Enterprise Financial & Operational Spreadsheet (XLSX) (spreadsheet_create)

1. Stack: Native Node.js xlsx-populate library.
2. Executive KPI Summary Cards: Feature prominent KPI cards on rows 1–3 displaying primary metrics, benchmark deltas, and theme accent borders.
3. Distinct Table Header & AutoFilter: Table headers use dark slate fill (#1E293B) with white bold text, freeze panes (ws.views = [{ state: 'frozen', ySplit: headerRow }]), and table AutoFilter (ws.autoFilter = { from: ..., to: ... }).
4. Dynamic Lookups & Formulas: Use standard UPPERCASE Excel formulas (SUM, AVERAGE, COUNTIF, and cross-sheet XLOOKUP). Lowercase formulas are strictly rejected.
5. Model Rigor: Zero bare decimals; format currency ($#,##0), percentages (0.0%), integer counts (#,##0), and durations (0.0 hrs).
6. View Setup: Zebra-stripe data rows (#FFFFFF and #F8FAFC), explicitly show gridlines (showGridLines = true), and auto-fit column widths with +4 padding.

---

SOP 7: Publication-Grade PDF Generation (document_create)

1. Stack: Native Node.js Playwright + HTML/CSS.
2. Contained A4 Portrait Scaling: Standardize on A4 portrait (794px x 1123px / 210mm x 297mm at 96 DPI).
3. Contained Cover Panel: Position cover content panel at left: 350px, width: 395px with a 49px right margin, strictly preventing text clipping or right-edge overflow.
4. CSS Paged Media Isolation:

   @page {
     size: A4 portrait;
     margin: 16mm 18mm 16mm 18mm;
     @top-right { content: "Enterprise Infrastructure Architecture"; }
     @bottom-right { content: "Page " counter(page) " of " counter(pages); }
   }
   

5. Running 4-Color Gradient Bar: Running header and footer bands with 4-color gradient bar matching the selected theme.
6. Typography Contract: Inter or Georgia (headings) + Inter or Calibri (body).
7. Metadata Sanitization: Normalize PDF metadata dictionary to standard executive attributes.

---

SOP 8: Scalable Vector Graphics (SVG) Diagram Creation (diagram_create)

1. Stack: Native SVG + CSS + TypeScript.
2. Responsive Canvas Architecture: Use clean semantic SVG elements (<svg>, <g>, <rect>, <path>, <text>) with explicit viewBox coordinates and contained geometry.
3. Theme Gradient Accents: Apply the 4-color gradient theme to node borders, service cluster boundaries, and active data pipelines.
4. Accessible Typography: System fonts (Inter, system-ui), high-contrast text labels (#334155), and descriptive aria labels.

---

SOP 9: Animated Diagram & Motion Export (animation_export)

1. Stack: Native Playwright + FFmpeg.
2. Canonical Format (Animated WebP): Mandate Animated WebP (.webp) as the primary and canonical animation output format across all documentation, architecture diagrams, and system walkthroughs. GIF format (.gif) and PNG sequences are preserved strictly as backward compatibility fallbacks.
3. High-Resolution Frame Capture: Headless Playwright (--disable-dev-shm-usage, --disable-gpu) renders and captures SVG/HTML keyframes at crisp display resolutions.
4. Optimized WebP Animation Encoding: FFmpeg compiles captured frames using libwebp_anim (-lossless 0 -compression_level 6 -q:v 50 -preset drawing -loop 0). This delivers $\ge 40%$ to $70%$ file size reduction over legacy GIF while preserving vector-sharp line clarity and text legibility.
5. Binary Structural Validation Gate: Every generated .webp artifact must pass automated binary validation via validateAnimatedWebP (verifying RIFF bitstream header, WEBP fourCC, VP8X extended header with animation flag bit 1 set, ANIM background/loop chunk, and sequential ANMF frame chunks). Corrupt, zero-frame, or non-animated files fail immediately and are removed.
6. Markdown Embedding Invariant: Technical documents, runbooks, and repository guides embed motion diagrams using standard Markdown syntax with .webp extensions (e.g. ![Architecture Flow](docs/diagrams/flow.webp)).

---

SOP 10: Zero-AI Human Voice & Authenticity Standard

1. Mathematical Burstiness Target ($\sigma/\mu \ge 0.85$): Enforce high sentence length variance within every paragraph to defeat commercial AI classifiers. Juxtapose punchy 3–7 word sentences with 24–38 word empirical clauses.
2. Purge of AI Clichés: Strictly ban all generative clichés in English ("testament", "delve", "leverage", "seamless", "paramount", "tapestry", "beacon", "orchestrate", "foster", "game-changer").
3. Primary Archival Grounding: Support assertions with verifiable technical metrics, shelfmarks, commit hashes, and benchmark measurements (87.4%, 142ms p99, v2.2.3).
4. Mandatory 0.0% AI Detection Score: All deliverables must achieve a clean 0.0% AI detection score via node bin/cli.js detect-docs.

---

Domain Routing

Based on the specific artifact request, refer to the corresponding reference guide in references/:

If the request involves...	Reference Guide
Microsoft Word documents, reports, proposals, native DOCX generation	tokubetsu-jonin-skill/docx
PowerPoint presentations, pitch decks, slide decks, PPTX	tokubetsu-jonin-skill/pptx
World-class presentation design, keynote decks, pitch templates	tokubetsu-jonin-skill/elite-powerpoint-designer
Excel spreadsheets, financial models, data tables, ROI analysis, XLSX	tokubetsu-jonin-skill/xlsx
Publication-grade PDF reports, whitepapers, Playwright HTML/CSS printing	tokubetsu-jonin-skill/pdf
Zero-AI human authenticity, document styling invariants, metadata scrubbing	tokubetsu-jonin-skill/zero-ai-human-writing
Documentation writing, README creation, technical guides, code documentation	tokubetsu-jonin-skill/documentation-writer
Complete documentation architecture, API references, runbooks	tokubetsu-jonin-skill/documentation-site-expert
Postmortems, incident reports, root cause analysis (RCA), project retrospectives	tokubetsu-jonin-skill/postmortem-writer
Technical articles, tutorials, engineering blogs, case studies	tokubetsu-jonin-skill/technical-article-writer
Final response shaping, ADHD-friendly concise output, action-first answers	tokubetsu-jonin-skill/i-have-adhd (i-have-adhd)