[{"data":1,"prerenderedAt":1643},["ShallowReactive",2],{"content-\u002Fplugins\u002Faio-planning\u002Faio-doc-writer":3,"children-\u002Fplugins\u002Faio-planning\u002Faio-doc-writer":1642,"twin-\u002Fplugins\u002Faio-planning\u002Faio-doc-writer":1637},{"id":4,"title":5,"author":6,"body":7,"budget_tier":6,"build_tags":6,"created":6,"description":1633,"document_type":1634,"extension":1635,"game":6,"install":36,"investment_tier":6,"league":6,"meta":1636,"navigation":1637,"patch":6,"path":1638,"plugin":24,"profit_per_hour":6,"ratings":6,"seo":1639,"skills_count":6,"status":6,"stem":1640,"strategy_tier":6,"tags":6,"updated":6,"version":6,"weight":6,"__hash__":1641},"content\u002Fplugins\u002Faio-planning\u002Faio-doc-writer.md","aio-doc-writer",null,{"type":8,"value":9,"toc":1609},"minimark",[10,37,47,52,62,67,70,80,90,96,102,106,109,149,155,159,162,200,207,212,215,223,226,230,233,259,262,266,277,283,287,290,295,350,356,364,367,371,379,385,389,395,401,409,413,418,423,469,473,479,485,491,501,507,511,516,527,532,535,567,570,596,600,603,608,616,621,627,632,638,644,648,651,655,661,735,742,745,774,778,781,787,791,794,800,804,807,851,863,869,873,876,880,887,892,930,935,979,984,1010,1014,1017,1023,1040,1049,1058,1063,1095,1105,1135,1140,1143,1149,1157,1164,1169,1198,1278,1302,1308,1314,1346,1355,1387,1390,1394,1397,1468,1471,1510,1514,1517,1523,1526,1533,1537,1543,1547,1550,1576,1581,1585,1597,1603],[11,12,13],"blockquote",{},[14,15,16,17,25,26,25,30,33,34],"p",{},"From plugin ",[18,19,21],"a",{"href":20},"\u002Fplugins\u002Faio-planning",[22,23,24],"strong",{},"aio-planning"," · ",[27,28,29],"code",{},"v1.1.2",[22,31,32],{},"Install:"," ",[27,35,36],{},"\u002Fplugin install aio-planning@aiocean-plugins",[38,39,45],"pre",{"className":40,"code":42,"language":43,"meta":44},[41],"language-bash","SCRIPTS=\"${CLAUDE_PLUGIN_ROOT}\u002Fskills\u002Faio-doc-writer\u002Fscripts\"\n","bash","",[27,46,42],{"__ignoreMap":44},[48,49,51],"h2",{"id":50},"environment","Environment",[53,54,55],"ul",{},[56,57,58,59],"li",{},"GitNexus: !",[27,60,61],{},"npx gitnexus status 2>\u002Fdev\u002Fnull && echo \"AVAILABLE\" || echo \"NOT INSTALLED\"",[63,64,66],"h1",{"id":65},"codebase-oracle","Codebase Oracle",[14,68,69],{},"Comprehensive architecture documentation powered by GitNexus knowledge graph combined with Oracle direct documentation writing and LSP precision analysis.",[14,71,72,75,76,79],{},[22,73,74],{},"Core Philosophy:"," Oracle ",[22,77,78],{},"writes all documentation from scratch"," using GitNexus's knowledge graph (structure, dependencies, clusters, flows, hybrid search) combined with LSP type-aware analysis and direct source code reading.",[14,81,82,85,86,89],{},[22,83,84],{},"What GitNexus Provides:"," A precomputed knowledge graph — nodes (functions, classes, modules), edges (imports, calls, inheritance), clusters (functional communities with cohesion scores), execution flows from entry points, and hybrid search (BM25 + semantic). All from a single ",[27,87,88],{},"npx gitnexus analyze",".",[14,91,92,95],{},[22,93,94],{},"What LSP Provides:"," Type-aware precision — hover info, exact reference counts, caller tracing, diagnostics, rename safety.",[14,97,98,101],{},[22,99,100],{},"What Oracle Provides:"," All written documentation — module docs, architecture analysis, key flows, dependency narratives, failure modes, design rationale, and decision guidance.",[48,103,105],{"id":104},"documentation-intent-contract","Documentation Intent Contract",[14,107,108],{},"Before writing or updating any docs, declare this contract:",[53,110,111,131,137,143],{},[56,112,113,116,117,120,121,120,124,120,127,130],{},[22,114,115],{},"Audience",": Who will use this doc (",[27,118,119],{},"new engineer",", ",[27,122,123],{},"oncall",[27,125,126],{},"feature owner",[27,128,129],{},"refactor owner",").",[56,132,133,136],{},[22,134,135],{},"Primary tasks",": Top 2-3 questions the reader should answer quickly.",[56,138,139,142],{},[22,140,141],{},"Decision horizon",": What decisions this doc supports (incident, refactor, onboarding, architecture review).",[56,144,145,148],{},[22,146,147],{},"Out of scope",": What this doc intentionally does not cover.",[14,150,151,152,89],{},"If user does not specify, infer from context and state assumptions explicitly in ",[27,153,154],{},"CODEBASE_MAP.md",[48,156,158],{"id":157},"evidence-and-confidence-protocol","Evidence and Confidence Protocol",[14,160,161],{},"Every non-trivial claim must be represented as:",[163,164,165,171,181,194],"ol",{},[56,166,167,170],{},[27,168,169],{},"Claim"," - factual statement.",[56,172,173,176,177,180],{},[27,174,175],{},"Evidence"," - one or more ",[27,178,179],{},"path:line"," references.",[56,182,183,186,187,190,191,89],{},[27,184,185],{},"Confidence"," - ",[27,188,189],{},"░░░░░"," to ",[27,192,193],{},"▓▓▓▓▓",[56,195,196,199],{},[27,197,198],{},"Impact"," - why this matters to decisions.",[14,201,202,203,206],{},"Unknowns must be written as ",[27,204,205],{},"Unknown"," with a concrete verification step. Never present assumptions as facts.",[14,208,209],{},[22,210,211],{},"Preferred inline evidence format:",[14,213,214],{},"Instead of separate claim tables, add evidence directly in prose:",[38,216,221],{"className":217,"code":219,"language":220,"meta":44},[218],"language-markdown","The request path is synchronous and DB-bound (`internal\u002Fhandler\u002Fhandler.go:42`,\n`internal\u002Frepository\u002Fmongodb.go:88`), creating high latency risk under load.\n","markdown",[27,222,219],{"__ignoreMap":44},[14,224,225],{},"Use claim tables only in CODEBASE_MAP.md for the cross-module summary, not inside individual module docs.",[48,227,229],{"id":228},"meaningfulness-criteria","Meaningfulness Criteria",[14,231,232],{},"Docs are \"meaningful\" only when they answer:",[53,234,235,241,247,253],{},[56,236,237,240],{},[22,238,239],{},"What exists"," (structure)",[56,242,243,246],{},[22,244,245],{},"Why it is designed this way"," (rationale)",[56,248,249,252],{},[22,250,251],{},"What can fail"," (failure modes, signals, recovery)",[56,254,255,258],{},[22,256,257],{},"What changes are risky"," (blast radius, test coverage, owner boundary)",[14,260,261],{},"If a section only describes structure without decision guidance, it is incomplete.",[48,263,265],{"id":264},"writing-quality-standards","Writing Quality Standards",[14,267,268,269,272,273,89],{},"Architecture docs must be ",[22,270,271],{},"clear, scannable, and decision-useful",". Full guide: ",[18,274,276],{"href":275},"references\u002Fwriting-quality","references\u002Fwriting-quality.md",[14,278,279,282],{},[22,280,281],{},"Key rules:"," Active voice, present tense, short sentences (\u003C25 words), lead with the point, concrete over abstract, no filler words (\"simply\", \"just\", \"easily\"). One term per concept throughout.",[48,284,286],{"id":285},"tool-availability-detection-run-first","Tool Availability Detection (Run First)",[14,288,289],{},"Before starting any phase, detect which analysis tools are available. Oracle adapts its workflow based on what's installed.",[14,291,292],{},[22,293,294],{},"Decision matrix:",[296,297,298,314],"table",{},[299,300,301],"thead",{},[302,303,304,308,311],"tr",{},[305,306,307],"th",{},"Tool",[305,309,310],{},"Status",[305,312,313],{},"Impact on Oracle",[315,316,317,329,340],"tbody",{},[302,318,319,323,326],{},[320,321,322],"td",{},"GitNexus",[320,324,325],{},"Required",[320,327,328],{},"Knowledge graph foundation — structure, deps, clusters, flows, search",[302,330,331,334,337],{},[320,332,333],{},"GitNexus MCP",[320,335,336],{},"Recommended",[320,338,339],{},"Enables graph queries directly; fallback: read JSON output",[302,341,342,345,347],{},[320,343,344],{},"LSP",[320,346,325],{},[320,348,349],{},"Precise type info, caller tracing, diagnostics",[14,351,352,355],{},[22,353,354],{},"If GitNexus is missing",", stop and inform the user:",[38,357,362],{"className":358,"code":360,"language":361},[359],"language-text","Tools detected:\n✗ GitNexus — MISSING (install: npm install -g gitnexus)\n✓ LSP — language servers available\n\nERROR: GitNexus is required. Install it before proceeding.\n","text",[27,363,360],{"__ignoreMap":44},[14,365,366],{},"Oracle will NOT proceed until GitNexus is available.",[48,368,370],{"id":369},"integration-architecture","Integration Architecture",[14,372,373,374,378],{},"GitNexus builds knowledge graph (Phase 0) → Oracle reads graph + analyzes with LSP (Phases 1-2) → Oracle writes all docs (Phase 3). See ",[18,375,377],{"href":376},"references\u002Farchitecture-analysis","references\u002Farchitecture-analysis.md"," for detailed architecture diagrams.",[14,380,381,384],{},[22,382,383],{},"Key principle:"," GitNexus provides the knowledge graph (structure, dependencies, clusters, flows). Oracle provides qualitative analysis and writes every doc.",[48,386,388],{"id":387},"gitnexus-knowledge-graph-output","GitNexus Knowledge Graph Output",[14,390,391,392,394],{},"After running ",[27,393,88],{},", GitNexus produces a knowledge graph with:",[38,396,399],{"className":397,"code":398,"language":361},[359],"Nodes:    Functions, classes, methods, interfaces (with file:line locations)\nEdges:    Import references, function calls, class inheritance, type usage\nClusters: Functional communities with cohesion scores\nFlows:    Execution paths from entry points\nSearch:   Hybrid BM25 + semantic search across the graph\n",[27,400,398],{"__ignoreMap":44},[14,402,403,406,407,89],{},[22,404,405],{},"MCP Integration:"," When GitNexus MCP server is configured, Oracle queries the graph directly using MCP tools. When not available, Oracle reads the JSON output from ",[27,408,88],{},[48,410,412],{"id":411},"workflow-documentation-generation","Workflow: Documentation Generation",[414,415,417],"h3",{"id":416},"quick-decision-tree","Quick Decision Tree",[14,419,420],{},[22,421,422],{},"What did the user ask for?",[296,424,425,435],{},[299,426,427],{},[302,428,429,432],{},[305,430,431],{},"User Request",[305,433,434],{},"Run These Phases",[315,436,437,445,453,461],{},[302,438,439,442],{},[320,440,441],{},"\"Analyze codebase\" \u002F \"Full analysis\"",[320,443,444],{},"All phases (0-3)",[302,446,447,450],{},[320,448,449],{},"\"Find missing docs\" \u002F \"What's not documented?\"",[320,451,452],{},"Phase 0, 1 only",[302,454,455,458],{},[320,456,457],{},"\"Update docs\" \u002F \"Refresh docs\"",[320,459,460],{},"Phase 0-3 (full re-run)",[302,462,463,466],{},[320,464,465],{},"\"Quick check\" \u002F \"Is this up to date?\"",[320,467,468],{},"Phase 1 only (review graph data)",[414,470,472],{"id":471},"phase-0-build-gitnexus-knowledge-graph-mandatory-first-step","Phase 0: Build GitNexus Knowledge Graph (MANDATORY first step)",[14,474,475,478],{},[22,476,477],{},"You MUST run GitNexus before any manual analysis."," Do not skip this step. Do not substitute with manual file reading. GitNexus generates the knowledge graph that Oracle uses as the foundation for documentation.",[38,480,483],{"className":481,"code":482,"language":43,"meta":44},[41],"# Run GitNexus analysis from the project root\nnpx gitnexus analyze\n\n# If GitNexus MCP server is configured, the graph is queryable via MCP tools\n# Otherwise, read the output JSON directly\n",[27,484,482],{"__ignoreMap":44},[14,486,487,490],{},[22,488,489],{},"Do NOT skip GitNexus and fall back to manual file reading"," — GitNexus provides dependency resolution, clustering, and flow tracing that manual analysis cannot replicate efficiently.",[14,492,493,500],{},[22,494,495,496,499],{},"If ",[27,497,498],{},"gitnexus"," is not installed",", inform the user:",[38,502,505],{"className":503,"code":504,"language":361},[359],"GitNexus is required. Install with: npm install -g gitnexus\n",[27,506,504],{"__ignoreMap":44},[414,508,510],{"id":509},"phase-1-scope-and-knowledge-graph-ingestion","Phase 1: Scope and Knowledge Graph Ingestion",[14,512,513],{},[22,514,515],{},"Decision: What mode to run?",[53,517,518,521,524],{},[56,519,520],{},"User wants \"quick check only\" → Run only Phase 1 (review data), report findings",[56,522,523],{},"User wants \"find gaps\" → Run Phase 1, identify undocumented modules\u002Fclusters",[56,525,526],{},"User wants \"full analysis\" → Run all phases (default)",[528,529,531],"h4",{"id":530},"_11-ingest-gitnexus-knowledge-graph","1.1 Ingest GitNexus Knowledge Graph",[14,533,534],{},"Read and parse GitNexus's knowledge graph output:",[163,536,537,543,549,555,561],{},[56,538,539,542],{},[22,540,541],{},"Extract nodes",": Functions, classes, methods with file:line locations",[56,544,545,548],{},[22,546,547],{},"Extract edges",": Import references, function calls, inheritance, type usage",[56,550,551,554],{},[22,552,553],{},"Extract clusters",": Functional communities with cohesion scores (these become module docs)",[56,556,557,560],{},[22,558,559],{},"Extract flows",": Execution paths from entry points",[56,562,563,566],{},[22,564,565],{},"Identify hubs",": High-connectivity nodes (these need blast radius analysis)",[14,568,569],{},"From the knowledge graph, identify:",[53,571,572,578,584,590],{},[56,573,574,577],{},[22,575,576],{},"Clusters\u002FCommunities",": Groups of related components (these become module docs)",[56,579,580,583],{},[22,581,582],{},"Hubs",": High fan-in nodes (these need blast radius analysis)",[56,585,586,589],{},[22,587,588],{},"Entry points",": Where execution flows begin",[56,591,592,595],{},[22,593,594],{},"Edges",": All relationship types between components",[528,597,599],{"id":598},"_12-detect-missing-context-infrastructure-serverless-multi-lang","1.2 Detect Missing Context (Infrastructure, Serverless, Multi-lang)",[14,601,602],{},"Scan for patterns that static analysis misses:",[14,604,605],{},[22,606,607],{},"Decision: Infrastructure detected?",[53,609,610,613],{},[56,611,612],{},"IF serverless.yml OR *.tf OR k8s\u002F found → Document in CODEBASE_MAP.md",[56,614,615],{},"IF no infrastructure files → Skip infrastructure sections",[14,617,618],{},[22,619,620],{},"Infrastructure & Runtime Detection:",[38,622,625],{"className":623,"code":624,"language":43,"meta":44},[41],"# Find serverless\u002Flambda configs\nfind . -name \"serverless.yml\" -o -name \"serverless.ts\" -o -name \"serverless.js\" -o -name \"template.yml\" -o -name \"samconfig.toml\"\n\n# Find Terraform\u002FK8s\nfind . -name \"*.tf\" -o -name \"*.tfvars\" -o -name \"*.yaml\" -path \"*\u002Fk8s\u002F*\" -o -name \"deployment.yaml\"\n\n# Find CI\u002FCD\nls .github\u002Fworkflows\u002F 2>\u002Fdev\u002Fnull || ls .gitlab-ci.yml 2>\u002Fdev\u002Fnull\n\n# Find workspace configs (monorepo)\ncat package.json | grep -A5 '\"workspaces\"' 2>\u002Fdev\u002Fnull\ncat nx.json 2>\u002Fdev\u002Fnull\ncat pnpm-workspace.yaml 2>\u002Fdev\u002Fnull\n",[27,626,624],{"__ignoreMap":44},[14,628,629],{},[22,630,631],{},"Cross-language Contracts:",[38,633,636],{"className":634,"code":635,"language":43,"meta":44},[41],"# Find protobuf, GraphQL, OpenAPI schemas\nfind . -name \"*.proto\" -o -name \"*.graphql\" -o -name \"*.gql\" -o -name \"openapi*.json\" -o -name \"openapi*.yaml\"\n",[27,637,635],{"__ignoreMap":44},[14,639,640,641,643],{},"Document these findings in ",[27,642,154],{}," under \"Infrastructure & Runtime Context\".",[414,645,647],{"id":646},"phase-2-analysis-pass-structure-meaning","Phase 2: Analysis Pass (Structure + Meaning)",[14,649,650],{},"Oracle reads actual source code and builds its understanding. Run parallel analysis agents per module\u002Fcluster.",[528,652,654],{"id":653},"_21-code-structure-analysis","2.1 Code Structure Analysis",[14,656,657,660],{},[22,658,659],{},"Method:"," Use GitNexus graph + LSP in order of precision.",[296,662,663,675],{},[299,664,665],{},[302,666,667,670,672],{},[305,668,669],{},"Priority",[305,671,307],{},[305,673,674],{},"Purpose",[315,676,677,690,703,722],{},[302,678,679,682,687],{},[320,680,681],{},"1st",[320,683,684,686],{},[22,685,322],{}," graph queries",[320,688,689],{},"Node inventory, edges, clusters, flows, hub detection",[302,691,692,695,700],{},[320,693,694],{},"2nd",[320,696,697,699],{},[22,698,322],{}," hybrid search",[320,701,702],{},"Cross-cutting patterns, semantic concept discovery",[302,704,705,708,719],{},[320,706,707],{},"3rd",[320,709,710,33,712,715,716],{},[22,711,344],{},[27,713,714],{},"lsp_document_symbols"," \u002F ",[27,717,718],{},"lsp_find_references",[320,720,721],{},"Type-aware symbols + precise caller tracing",[302,723,724,727,732],{},[320,725,726],{},"4th",[320,728,729],{},[22,730,731],{},"Read + Grep",[320,733,734],{},"Fill gaps, read implementations",[14,736,737,738,89],{},"For detailed tool commands and usage patterns, see ",[18,739,741],{"href":740},"references\u002Ftools-integration","references\u002Ftools-integration.md",[14,743,744],{},"Steps for each cluster:",[163,746,747,750,756,759,765,768,771],{},[56,748,749],{},"Query GitNexus graph for nodes in this cluster (functions, classes, deps)",[56,751,752,753,755],{},"Enrich with LSP (",[27,754,714],{},") for type-aware hierarchy",[56,757,758],{},"Map dependencies from GitNexus edges (imports, calls, inheritance)",[56,760,761,762,764],{},"For hub nodes: GitNexus flow tracing + LSP ",[27,763,718],{}," for blast radius",[56,766,767],{},"GitNexus hybrid search for cross-cutting patterns (\"error handling\", \"retry logic\")",[56,769,770],{},"Read + Grep to fill gaps",[56,772,773],{},"Build comprehensive module understanding with evidence (path:line)",[528,775,777],{"id":776},"_22-infrastructure-runtime-analysis","2.2 Infrastructure & Runtime Analysis",[14,779,780],{},"For modules with detected infrastructure context (Lambda, serverless, containers):",[38,782,785],{"className":783,"code":784,"language":361},[359],"Analyze infrastructure:\n- Does serverless.yml match the handler code?\n- What are the Lambda triggers and their configuration?\n- What Terraform resources exist and what code paths do they support?\n- What is the runtime (Node18, Python3.11, Go1.21)?\n",[27,786,784],{"__ignoreMap":44},[528,788,790],{"id":789},"_23-cross-language-contract-analysis","2.3 Cross-Language Contract Analysis",[14,792,793],{},"For monorepos with multiple languages:",[38,795,798],{"className":796,"code":797,"language":361},[359],"Analyze contract consistency:\n- Does protobuf schema match both Go and TypeScript implementations?\n- Are GraphQL resolvers in sync with schema definitions?\n- Do OpenAPI specs match the actual endpoint handlers?\n",[27,799,797],{"__ignoreMap":44},[528,801,803],{"id":802},"_24-meaning-analysis-why-and-risk","2.4 Meaning Analysis (Why and Risk)",[14,805,806],{},"For each module, build decision-support context:",[163,808,809,815,821,827,833,839,845],{},[56,810,811,814],{},[22,812,813],{},"Design rationale",": infer from code, tests, comments, history.",[56,816,817,820],{},[22,818,819],{},"Trade-offs",": what was optimized, what was sacrificed.",[56,822,823,826],{},[22,824,825],{},"Failure modes",": how it breaks, detection signals, first recovery actions.",[56,828,829,832],{},[22,830,831],{},"Change impact",": blast radius, downstream dependents, relevant tests.",[56,834,835,838],{},[22,836,837],{},"Ownership boundary",": which directory\u002Fservice boundaries are crossed.",[56,840,841,844],{},[22,842,843],{},"Runtime context"," (for serverless\u002FLambda): cold start implications, timeout risks, concurrency limits",[56,846,847,850],{},[22,848,849],{},"Infrastructure dependencies",": required IAM permissions, VPC config, external service dependencies",[14,852,853,856,857,859,860,862],{},[22,854,855],{},"Enhanced blast radius:"," For hub nodes (5+ dependents), use GitNexus flow tracing for transitive impact and ",[27,858,718],{}," for exact call sites. See ",[18,861,741],{"href":740}," for commands and interpretation.",[14,864,865,868],{},[22,866,867],{},"Pattern discovery:"," Use GitNexus hybrid search to find cross-cutting patterns (\"error handling strategy\", \"retry and resilience pattern\"). Document discovered patterns in module docs under \"Design Patterns\".",[414,870,872],{"id":871},"phase-3-write-documentation","Phase 3: Write Documentation",[14,874,875],{},"Oracle writes all documentation from scratch using analysis data from Phase 2.",[528,877,879],{"id":878},"templates","Templates",[14,881,882,883,886],{},"All 17 doc templates live in this skill's ",[27,884,885],{},"templates\u002F"," directory. Use them as structural guides — Oracle fills with analysis data from GitNexus graph and direct source code reading.",[14,888,889],{},[22,890,891],{},"Structure & analysis:",[53,893,894,900,906,912,918,924],{},[56,895,896,899],{},[27,897,898],{},"overview.md.tpl"," — project overview, health dashboard, module map",[56,901,902,905],{},[27,903,904],{},"module.md.tpl"," — per-module: components, hubs, deps, quality metrics",[56,907,908,911],{},[27,909,910],{},"architecture.md.tpl"," — C4 diagrams, layer map, community detection, design decisions",[56,913,914,917],{},[27,915,916],{},"component.md.tpl"," — per-component: signature, metrics, dependencies",[56,919,920,923],{},[27,921,922],{},"dependencies.md.tpl"," — dependency graph, hubs, blast radius, circular deps",[56,925,926,929],{},[27,927,928],{},"quality.md.tpl"," — complexity hotspots, maintainability index, violations",[14,931,932],{},[22,933,934],{},"Cross-cutting concerns:",[53,936,937,943,949,955,961,967,973],{},[56,938,939,942],{},[27,940,941],{},"key-flows.md.tpl"," — cross-module execution paths and sequence diagrams",[56,944,945,948],{},[27,946,947],{},"api-surface.md.tpl"," — API endpoints, contracts, versioning",[56,950,951,954],{},[27,952,953],{},"data-model.md.tpl"," — data schemas, relationships, migrations",[56,956,957,960],{},[27,958,959],{},"infrastructure.md.tpl"," — deployment, runtime, infrastructure-as-code",[56,962,963,966],{},[27,964,965],{},"testing.md.tpl"," — test architecture, coverage mapping, test-to-component traceability",[56,968,969,972],{},[27,970,971],{},"observability.md.tpl"," — logging, metrics, tracing, health checks, alerting",[56,974,975,978],{},[27,976,977],{},"security.md.tpl"," — trust boundaries, auth flows, secrets management, input validation",[14,980,981],{},[22,982,983],{},"Process & navigation:",[53,985,986,992,998,1004],{},[56,987,988,991],{},[27,989,990],{},"onboarding.md.tpl"," — getting started, dev workflow, common tasks",[56,993,994,997],{},[27,995,996],{},"adr.md.tpl"," — architecture decision records (explicit + inferred from code)",[56,999,1000,1003],{},[27,1001,1002],{},"product-requirements.md.tpl"," — functional requirements traceability",[56,1005,1006,1009],{},[27,1007,1008],{},"CODEBASE_MAP.md.tpl"," — Oracle index document with priorities and unknowns",[528,1011,1013],{"id":1012},"writing-each-module-doc","Writing each module doc",[14,1015,1016],{},"For each module\u002Fcluster identified in Phase 1:",[14,1018,1019,1022],{},[22,1020,1021],{},"Step 1: Write the module doc from scratch"," using:",[53,1024,1025,1031,1034,1037],{},[56,1026,1027,1028,1030],{},"Templates from ",[27,1029,885],{}," directory as structural guides",[56,1032,1033],{},"GitNexus cluster data (nodes, edges, cohesion scores, flows)",[56,1035,1036],{},"LSP type information and reference counts",[56,1038,1039],{},"Direct source code reading from Phase 2",[14,1041,1042,1045,1046,1048],{},[22,1043,1044],{},"Step 2: Add evidence inline."," Sprinkle ",[27,1047,179],{}," references throughout, not in a separate table. Example:",[53,1050,1051],{},[56,1052,1053,1054,1057],{},"\"The handler validates the request payload (",[27,1055,1056],{},"internal\u002Fhandler\u002Fcreate.go:45",")\"",[14,1059,1060],{},[22,1061,1062],{},"Step 3: Include decision-support sections where they naturally belong:",[53,1064,1065,1071,1077,1083,1089],{},[56,1066,1067,1070],{},[22,1068,1069],{},"Design Rationale"," near the architecture section",[56,1072,1073,1076],{},[22,1074,1075],{},"Failure Modes & Recovery"," after the component\u002Fflow descriptions",[56,1078,1079,1082],{},[22,1080,1081],{},"Blast Radius & Safe Change Plan"," near the dependency section",[56,1084,1085,1088],{},[22,1086,1087],{},"Infrastructure Context"," (Lambda config, IAM, VPC) near deployment\u002Fruntime sections",[56,1090,1091,1094],{},[22,1092,1093],{},"Unknowns"," at the end — things Oracle couldn't verify with concrete next steps",[14,1096,1097,1100,1101,1104],{},[22,1098,1099],{},"Step 4: Writing quality pass."," Apply ",[18,1102,265],{"href":1103},"#writing-quality-standards",":",[163,1106,1107,1110,1113,1116,1119,1122,1125,1128],{},[56,1108,1109],{},"Active voice, present tense, short sentences (under 25 words)",[56,1111,1112],{},"Lead with the point — first sentence of each paragraph states the main idea",[56,1114,1115],{},"Replace vague language with specifics: exact counts, concrete names, measured values",[56,1117,1118],{},"Cut filler words: \"simply\", \"just\", \"note that\", \"there is\u002Fare\", weasel words",[56,1120,1121],{},"Consistent terminology — same concept = same word throughout",[56,1123,1124],{},"Each section answers \"so what?\" for the target audience",[56,1126,1127],{},"Heading hierarchy: sentence case, levels increment by one, no trailing punctuation",[56,1129,1130,1131,1134],{},"Scrub sensitive data: replace real webhook URLs, bot tokens, API keys, personal names from git config, and ",[27,1132,1133],{},"\u002FUsers\u002Fusername\u002F..."," paths with generic placeholders",[14,1136,1137],{},[22,1138,1139],{},"Step 5: Append compact Oracle metadata footer.",[14,1141,1142],{},"Only metadata goes at the bottom:",[38,1144,1147],{"className":1145,"code":1146,"language":220,"meta":44},[218],"\u003C!-- ORACLE-META\nWritten by codebase-oracle | {timestamp}\nData: GitNexus knowledge graph + LSP + direct source reading\nAudience: {audience} | Confidence: {overall}%\nUnknowns: {N} items pending verification\n-->\n",[27,1148,1146],{"__ignoreMap":44},[14,1150,1151],{},[22,1152,1153,1154,130],{},"Step 6: Generate interactive graph viewer (",[27,1155,1156],{},"graph.html",[14,1158,1159,1160,1163],{},"The ",[27,1161,1162],{},"graph.html.tpl"," template lives in this skill's directory. It produces a self-contained D3 force-directed graph with module clustering, convex hulls, colored links, search, tooltips, minimap, and keyboard shortcuts.",[14,1165,1166],{},[22,1167,1168],{},"How to generate:",[163,1170,1171,1179,1185],{},[56,1172,1173,33,1176,1178],{},[22,1174,1175],{},"Read the template",[27,1177,1162],{}," from this skill's directory.",[56,1180,1181,1184],{},[22,1182,1183],{},"Read GitNexus graph data"," — nodes, edges, clusters.",[56,1186,1187,1193,1194,1197],{},[22,1188,1189,1190],{},"Copy the template to ",[27,1191,1192],{},"docs\u002Fgraph.html"," and fill in the JavaScript data blocks near the top of ",[27,1195,1196],{},"\u003Cscript>",". Map GitNexus graph data to:",[296,1199,1200,1213],{},[299,1201,1202],{},[302,1203,1204,1207,1210],{},[305,1205,1206],{},"Data block",[305,1208,1209],{},"Source",[305,1211,1212],{},"Description",[315,1214,1215,1231,1247,1262],{},[302,1216,1217,1222,1225],{},[320,1218,1219],{},[27,1220,1221],{},"filesData",[320,1223,1224],{},"GitNexus nodes",[320,1226,1227,1228],{},"Object keyed by file path. Each: ",[27,1229,1230],{},"{functions, max_complexity, hub_count, community_ids, function_names}",[302,1232,1233,1238,1241],{},[320,1234,1235],{},[27,1236,1237],{},"edgesData",[320,1239,1240],{},"GitNexus edges",[320,1242,1243,1244],{},"Array of ",[27,1245,1246],{},"{source, target, weight}",[302,1248,1249,1254,1257],{},[320,1250,1251],{},[27,1252,1253],{},"summaryData",[320,1255,1256],{},"Graph metrics",[320,1258,1259],{},[27,1260,1261],{},"{total_nodes, total_edges, hub_files, circular_dependencies}",[302,1263,1264,1269,1272],{},[320,1265,1266],{},[27,1267,1268],{},"moduleConfig",[320,1270,1271],{},"GitNexus clusters",[320,1273,1274,1277],{},[27,1275,1276],{},"{\"Module Name\": {color: \"#hex\", files: [...]}}"," per cluster",[163,1279,1281,1295],{"start":1280},4,[56,1282,1283,1286,1287,1290,1291,1294],{},[22,1284,1285],{},"Replace the title"," — Change ",[27,1288,1289],{},"\u003Ctitle>"," and ",[27,1292,1293],{},"\u003Ch1>"," to the actual project name.",[56,1296,1297,89],{},[22,1298,1299,1300],{},"Write to ",[27,1301,1192],{},[14,1303,1304,1305],{},"Color palette for modules: ",[27,1306,1307],{},"#58a6ff, #f78166, #d2a8ff, #7ee787, #f0883e, #79c0ff, #ffa657, #ff7b72, #3fb950, #a5d6ff",[14,1309,1310,1311,1313],{},"Generate ",[27,1312,154],{}," as the index of all Oracle-written module docs and include:",[53,1315,1316,1319,1325,1331,1337,1340,1343],{},[56,1317,1318],{},"Audience + primary tasks",[56,1320,1321,1324],{},[22,1322,1323],{},"Infrastructure & Runtime Context"," (Lambdas, containers, scheduled jobs)",[56,1326,1327,1330],{},[22,1328,1329],{},"Multi-language boundaries"," (which modules use which languages, how they communicate)",[56,1332,1333,1336],{},[22,1334,1335],{},"Monorepo structure"," (workspaces, shared packages, build order)",[56,1338,1339],{},"Top risky hubs",[56,1341,1342],{},"Most critical unknowns",[56,1344,1345],{},"Priority recommendations for next engineering work",[14,1347,1348,1351,1352,1354],{},[22,1349,1350],{},"Multi-diagram architecture section."," Include separate Mermaid diagrams for each concern (see ",[18,1353,377],{"href":376}," for templates):",[163,1356,1357,1363,1369,1375,1381],{},[56,1358,1359,1362],{},[22,1360,1361],{},"C4 Context"," — system boundary, users, external dependencies",[56,1364,1365,1368],{},[22,1366,1367],{},"Module\u002Fdomain relationships"," — internal component ownership and communication",[56,1370,1371,1374],{},[22,1372,1373],{},"Infrastructure topology"," — where things run (Lambda, containers, databases, queues)",[56,1376,1377,1380],{},[22,1378,1379],{},"Key data flows"," — sequence diagrams for critical request paths",[56,1382,1383,1386],{},[22,1384,1385],{},"Dependency graph"," — hub nodes highlighted, blast radius annotated",[14,1388,1389],{},"Do not flatten everything into a single overview diagram. Each diagram answers a different question.",[48,1391,1393],{"id":1392},"rules","Rules",[14,1395,1396],{},"ALWAYS:",[53,1398,1399,1405,1411,1417,1426,1432,1435,1438,1441,1444,1450,1456,1462],{},[56,1400,1401,1404],{},[22,1402,1403],{},"Write all documentation from scratch"," — Oracle is the sole author",[56,1406,1407,1410],{},[22,1408,1409],{},"Use GitNexus knowledge graph as the foundation"," (structure, dependencies, clusters, flows, search)",[56,1412,1413,1416],{},[22,1414,1415],{},"Read actual source code for all qualitative claims"," — never rely solely on graph data",[56,1418,1419,1422,1423,1425],{},[22,1420,1421],{},"Add evidence inline"," (",[27,1424,179],{},") throughout the content, not in a separate table",[56,1427,1428,1431],{},[22,1429,1430],{},"Insert sections where they belong"," — failure modes near flows, blast radius near dependencies",[56,1433,1434],{},"Produce one coherent document that reads naturally",[56,1436,1437],{},"Generate single CODEBASE_MAP.md as index",[56,1439,1440],{},"Start with Documentation Intent Contract (audience, tasks, decision horizon)",[56,1442,1443],{},"Include rationale, trade-offs, failure modes, and safe-change guidance",[56,1445,1446,1447,1449],{},"Use ",[27,1448,205],{}," + verification steps for things Oracle couldn't verify",[56,1451,1452,1455],{},[22,1453,1454],{},"Scan for infrastructure context"," (serverless.yml, terraform, k8s) and document runtime behavior",[56,1457,1458,1461],{},[22,1459,1460],{},"Detect monorepo structure"," (workspaces, nx.json) and document package boundaries",[56,1463,1464,1467],{},[22,1465,1466],{},"Trace cross-language contracts"," (protobuf, GraphQL, OpenAPI) when multiple languages present",[14,1469,1470],{},"NEVER:",[53,1472,1473,1479,1485,1488,1501,1504,1507],{},[56,1474,1475,1478],{},[22,1476,1477],{},"Append a \"validation report\" section"," — there is nothing to validate against",[56,1480,1481,1484],{},[22,1482,1483],{},"Duplicate information"," — don't repeat content in both the doc body and a footer table",[56,1486,1487],{},"Create separate validation docs alongside module docs",[56,1489,1490,1491,120,1494,120,1497,1500],{},"Reference ",[27,1492,1493],{},".codeindex-cache\u002F",[27,1495,1496],{},"module_tree.json",[27,1498,1499],{},"codebase_map.json"," — these are from the old CodeIndex system",[56,1502,1503],{},"Write high-confidence claims without evidence",[56,1505,1506],{},"Leave generic summaries that do not help decisions",[56,1508,1509],{},"Hide uncertainty when evidence is incomplete",[48,1511,1513],{"id":1512},"quality-gates","Quality Gates",[14,1515,1516],{},"Run the bundled quality checker after writing docs:",[38,1518,1521],{"className":1519,"code":1520,"language":43,"meta":44},[41],"bash $SCRIPTS\u002Fdoc-quality-check.sh docs\n",[27,1522,1520],{"__ignoreMap":44},[14,1524,1525],{},"Key gates: evidence density (path:line refs), no placeholders, unknowns section required, no filler words, no sensitive data leakage.",[14,1527,1528,1529,89],{},"For full gate definitions and manual check commands, see ",[18,1530,1532],{"href":1531},"references\u002Fquality-gates","references\u002Fquality-gates.md",[48,1534,1536],{"id":1535},"output-structure","Output Structure",[38,1538,1541],{"className":1539,"code":1540,"language":361},[359],"docs\u002F\n├── CODEBASE_MAP.md              # Oracle-written index with priorities and unknowns\n├── {module}.md                  # Oracle-written module docs (one per cluster)\n│   ├── Data from GitNexus graph + LSP + source code reading\n│   ├── Evidence (path:line) throughout\n│   ├── Decision-support sections (failure modes, blast radius, rationale)\n│   └── \u003C!-- ORACLE-META --> compact footer\n└── graph.html                   # Interactive D3 viewer (from skill's graph.html.tpl)\n",[27,1542,1540],{"__ignoreMap":44},[48,1544,1546],{"id":1545},"external-tools-integration","External Tools Integration",[14,1548,1549],{},"Oracle requires GitNexus + LSP for comprehensive analysis. Each provides a unique dimension.",[296,1551,1552,1561],{},[299,1553,1554],{},[302,1555,1556,1558],{},[305,1557,307],{},[305,1559,1560],{},"Primary Use",[315,1562,1563,1570],{},[302,1564,1565,1567],{},[320,1566,322],{},[320,1568,1569],{},"Knowledge graph: structure, dependencies, clusters, flows, hybrid search",[302,1571,1572,1574],{},[320,1573,344],{},[320,1575,349],{},[14,1577,1578,1579,89],{},"For detailed tool commands, comparison matrix, setup instructions, and usage guidelines, see ",[18,1580,741],{"href":740},[48,1582,1584],{"id":1583},"troubleshooting","Troubleshooting",[14,1586,1587,1590,1591,1594,1595,89],{},[22,1588,1589],{},"GitNexus not installed:"," Install with ",[27,1592,1593],{},"npm install -g gitnexus"," or use ",[27,1596,88],{},[14,1598,1599,1602],{},[22,1600,1601],{},"GitNexus MCP not configured:"," Oracle can still work by reading GitNexus JSON output directly. MCP integration is recommended for interactive graph queries.",[14,1604,1605,1608],{},[22,1606,1607],{},"LSP not available:"," Configure language servers for your project's languages. Without LSP, Oracle loses type-aware analysis but can still produce docs from GitNexus graph + source reading.",{"title":44,"searchDepth":1610,"depth":1610,"links":1611},2,[1612,1613,1614,1615,1616,1617,1618,1619,1620,1628,1629,1630,1631,1632],{"id":50,"depth":1610,"text":51},{"id":104,"depth":1610,"text":105},{"id":157,"depth":1610,"text":158},{"id":228,"depth":1610,"text":229},{"id":264,"depth":1610,"text":265},{"id":285,"depth":1610,"text":286},{"id":369,"depth":1610,"text":370},{"id":387,"depth":1610,"text":388},{"id":411,"depth":1610,"text":412,"children":1621},[1622,1624,1625,1626,1627],{"id":416,"depth":1623,"text":417},3,{"id":471,"depth":1623,"text":472},{"id":509,"depth":1623,"text":510},{"id":646,"depth":1623,"text":647},{"id":871,"depth":1623,"text":872},{"id":1392,"depth":1610,"text":1393},{"id":1512,"depth":1610,"text":1513},{"id":1535,"depth":1610,"text":1536},{"id":1545,"depth":1610,"text":1546},{"id":1583,"depth":1610,"text":1584},"Generate comprehensive architecture documentation powered by GitNexus knowledge graph and LSP analysis.","skill","md",{},true,"\u002Fplugins\u002Faio-planning\u002Faio-doc-writer",{"title":5,"description":1633},"plugins\u002Faio-planning\u002Faio-doc-writer","MKig-83xYXibT25a1UG8KRUmPXPRV25RMyqHBfBKrjE",[],1779712313587]