| name | wiki-sync |
| description | Compiles and maintains `/wiki` as a generated, provenance-aware, cross-linked semantic projection of `/docs`. Supports automatic incremental sync and forced rebuild/lint/repair/consolidation flows. The generated wiki must remain suitable both for agent reasoning and for frontend-rendered onboarding/reference experiences for project newcomers. |
Wiki Sync Skill
Purpose
This skill maintains a generated /wiki directory as a semantic projection of the human-authored /docs directory.
/docs is the normative source layer.
/wiki is the compiled interpretation layer.
The agent MUST treat /docs as the authoritative source of truth and /wiki as a maintained derivative artifact optimized for navigation, synthesis, cross-linking, query-time reasoning, and frontend rendering.
The generated /wiki MUST serve two audiences simultaneously:
- Agents, which need compact, structured, provenance-aware semantic access and graph-shaped navigation for query-time reasoning
- Human newcomers, which need clear onboarding-oriented explanations, stable navigation, and low-friction discovery of core concepts
The agent MUST optimize wiki output for both machine readability and frontend rendering quality. Token savings are a useful side effect of a compact semantic projection, not the primary objective; the primary objective is truthful, navigable, provenance-aware project exploration.
Core Model
Source Authority
The agent MUST apply the following authority order:
/docs authoritative human-authored content- Explicit repository metadata relevant to docs/wiki sync
- Existing
/wiki pages as prior generated artifacts
- Inferred structure generated by the agent
The agent MUST NEVER allow /wiki to override /docs.
The agent MUST NEVER silently preserve a wiki claim that conflicts with updated evidence in /docs.
Strict OKF Bundle Contract
Read the bundled Open Knowledge Format reference before changing Wiki schema, validation, provenance, lifecycle, trust, or reserved-file behavior. This directly readable Markdown atom embeds its lock metadata and the full adopted upstream source; project extensions remain subordinate to it.
/wiki is an explicitly declared strict OKF v0.2 bundle. Root index.md declares okf_version: "0.2"; exact index.md is reserved and is not a localized concept or graph node. Every other Markdown concept uses canonical type, description, and structured sources[].resource. DEOS locale, audience, related-link, and explicit lifecycle fields remain compatible extensions. Do not emit page_type or summary aliases, and never infer generated, verified, stale_after, attestation, or freshness evidence from dates, Git history, or structural validation.
Strict OKF scope ends at /wiki; /docs, repository context, Skills, and unrelated Markdown are not members of this bundle merely because they use frontmatter.
The reference frontmatter is the only publication atom. Its embedded lock binds the adopted version, immutable upstream revision and blob, upstream-source SHA-256, deterministic body SHA-256, and separate DEOS Wiki adoption state without a self-referential whole-file hash or a second rename. Before changing OKF schema, provenance, lifecycle, reserved files, or validation, agents MUST run the optional network freshness check:
npm run okf:check --prefix .agents/skills/wiki-sync
Lifecycle output is current, unknown, review-pending, or adopted. current means the pinned source matches the freshest upstream GoogleCloudPlatform/knowledge-catalog/okf/SPEC.md; it does not newly prove Wiki compatibility. unknown means GitHub was unavailable while the verified local atom remains valid. review-pending is read-only classification. adopted is emitted only after successful publication and is the canonical embedded adoption status. This network check is intentionally outside ordinary offline completion gates.
Reference refresh is staged and explicit. npm run okf:sync --prefix .agents/skills/wiki-sync -- --reviewed fetches metadata, then one immutable commit, checks blob and SHA identities, and publishes the single atom only after strict tests pass. Changed content under the same version additionally needs --allow-same-version-revision; a newer minor needs --allow-version-change; a newer major needs --allow-breaking-version. Version changes are refused until wiki/index.md already declares the migrated version. These flags record review authority only: agents MUST first inspect the candidate semantics and complete the dependent validator/schema migration. Never describe reference freshness as protocol adoption.
Layer Semantics
/docs:
- Human-authored
- Normative or primary explanatory content
- Source of truth
- May contain drafts, deprecated pages, or superseded pages
- MUST NOT be rewritten by this skill unless the user explicitly asks for edits to
/docs
/wiki:
- Agent-maintained
- Synthesized
- Cross-linked
- Query-optimized
- Frontend-renderable
- Allowed to merge information from multiple docs
- MUST remain traceable back to
/docs
- MUST NOT introduce stronger claims than supported by
/docs
Semantic Compilation
The agent MUST treat wiki synchronization as semantic compilation rather than mere summarization.
The objective is not to duplicate /docs.
The objective is to maintain a compact, truthful, navigable, provenance-aware, cross-linked knowledge surface aligned with /docs and suitable for both agent use and newcomer-facing UI rendering. A page is valid only when it improves human onboarding, frontend reference navigation, or agent traversal of the project knowledge graph.
Goals
The agent using this skill MUST:
- Detect meaningful changes in
/docs
- Determine which wiki pages are affected
- Create or update only the necessary pages in
/wiki
- Preserve provenance for nontrivial claims
- Maintain compact locale-scoped index entrypoints such as
index.en.md and index.<locale>.md
- Detect contradictions, stale pages, weak pages, duplicate concepts, broken links, and navigation drift
- Support full rebuild when explicitly requested
- Keep the wiki legible to both humans and agents
- Keep the wiki structurally suitable for a frontend knowledge section
- Avoid epistemic drift between
/docs and /wiki
- Improve newcomer onboarding quality as the docs evolve
Non-Goals
This skill MUST NOT:
- Act as a generic search engine
- Rewrite
/docs unless explicitly asked
- Invent unsupported facts
- Silently discard contradictions
- Silently flatten uncertainty into certainty
- Turn
/wiki into a second uncontrolled documentation tree
- Require
/wiki to exist for the project to function
- Make
/wiki part of the build-critical path unless the repository explicitly requires it
- Optimize only for insiders while neglecting newcomer readability
- Emit pages that depend on private conversational context not grounded in
/docs
Invocation Modes
Automatic Mode
The agent SHOULD run this skill automatically when one or more files under /docs are added, changed, moved, deprecated, superseded, or deleted.
Automatic mode SHOULD prefer incremental synchronization over full rebuild.
Automatic mode SHOULD update only the affected wiki artifacts unless structural drift, schema drift, or large-scale doc changes make rebuild necessary.
Forced Mode
The agent MUST support explicit forced invocation when the user or caller requests actions such as:
- Sync wiki
- Update wiki
- Refresh wiki
- Rebuild wiki
- Recompile wiki
- Lint wiki
- Consolidate wiki
- Repair wiki
- Regenerate wiki from docs
- Regenerate one page
- Refresh frontend-facing summaries
- Rebuild onboarding pages
Forced mode MAY run even if no changes are detected.
Forced mode MUST obey the specific requested scope if provided.
Examples:
- Sync only changed pages
- Rebuild everything
- Lint only
- Consolidate weak pages and supersession
- Repair links and index
- Regenerate one page from selected docs
- Rebuild overview and glossary pages only
Expected Repository Structure
This skill assumes a repository layout roughly like:
.agents/skills/wiki-sync/SKILL.md
/docs/
/wiki/
The skill SHOULD work even if /wiki does not yet exist.
The skill MAY create the following files or directories under /wiki:
/wiki/index.en.md
/wiki/index.<locale>.md
/wiki/_meta/
/wiki/_meta/navigation.json
/wiki/_meta/state.json
/wiki/_meta/graph.json
/wiki/_meta/aliases.json
/wiki/_meta/locales.json
Exact layout MAY vary by repository convention, but the semantic roles MUST remain stable.
Recommended Wiki Layout
A preferred layout is:
/wiki/index.en.md
/wiki/index.<locale>.md
/wiki/overview/
/wiki/getting-started/
/wiki/concepts/
/wiki/entities/
/wiki/processes/
/wiki/decisions/
/wiki/comparisons/
/wiki/glossary/
/wiki/faq/
/wiki/status/
/wiki/timeline/
/wiki/_meta/navigation.json
/wiki/_meta/state.json
/wiki/_meta/graph.json
/wiki/_meta/aliases.json
/wiki/_meta/locales.json
If the repository already has a different wiki layout, the agent SHOULD adapt to the existing structure rather than forcing a migration unless the user explicitly requests restructuring.
Required Artifacts
index.<locale>.md
The wiki MUST contain locale-scoped root entrypoints such as index.en.md and any requested mirrored locales like index.ru.md.
Each index.<locale>.md MUST:
- Remain concise enough for efficient agent use
- Expose the high-level topic structure
- Link to major wiki pages in the same locale when those mirrors exist
- Surface recently changed areas when useful
- Provide discoverable entry paths for newcomers
- Avoid becoming a full duplicate of the wiki contents
The agent SHOULD treat the default-locale index.<locale>.md as the primary navigation surface for compatibility-sensitive consumers, while still keeping locale mirrors aligned.
Delivery History
The wiki MUST NOT maintain separate mutation log files by default.
Completed wiki delivery work belongs in the project-level delivery history, normally CHANGELOG.md, unless a repository explicitly introduces a different canonical history surface.
The wiki may preserve explicit lifecycle, provenance, and graph state through _meta/*.json, but those metadata artifacts are not a second changelog.
Locale Mirroring Contract
The wiki MUST treat internationalization as a first-class structural contract rather than an afterthought.
The agent MUST ensure:
- All human-facing wiki markdown files use a locale suffix such as
.<locale>.md
- The current default locale is
en unless the repository states otherwise
- Non-default locale pages mirror the same page ids and relative path topology as the default locale
- Locale audits derive their complete expected page set from the canonical locale manifest; never freeze page counts in validators or reviewer instructions
- Localized internal links point to localized wiki pages when those mirrors exist
- Localized metadata with user-facing strings or locale-specific paths is stored inside shared JSON manifests through language-keyed objects such as
title: { en: ..., ru: ... }
- A locale manifest such as
_meta/locales.json exists when the repository needs an explicit supported-locale map
If localized source docs are incomplete, the agent MAY generate a truthful mirror page from the default-locale wiki page, but it MUST mark that page explicitly with metadata such as translation_of and translation_status: mirrored-from-default instead of pretending full source-localized synthesis exists.
Native Localization Contract
Locale mirrors preserve semantic claims, provenance, page identity, graph topology, and link intent; they are not required to preserve English sentence structure or literal phrasing.
For Russian pages and localized frontend strings, the agent MUST write natural native Russian, replace avoidable anglicisms and calques with established Russian equivalents, and restructure headings, examples, and explanations when needed for fluency. Preserve canonical project identifiers, code symbols, asset symbols, and technical terms whose translation would reduce precision. Localization MUST NOT introduce a stronger claim, omit an invariant, or drift from the source contract merely to sound natural.
Read and follow Native Russian Wiki Style before Russian localization work. Its reviewed inventory and structural exact-term exclusions provide a deterministic regression gate, while its independent bilingual handoff remains the evidence owner for native fluency.
Review each Russian surface as independent prose after semantic parity is established; a mechanically mirrored translation is not complete localization evidence.
Page-Level Provenance
Each nontrivial wiki page MUST reference its supporting doc sources.
This MAY appear in frontmatter, a source section, sidecar metadata, or a combination of those.
Optional Metadata Artifacts
If repository conventions allow, the agent SHOULD maintain:
navigation.json for localized navigation strings and localized wiki paths stored as language-keyed objects inside one manifeststate.json for explicit status, provenance, supersession, and other page-level state, with localized fields grouped under language keys where neededgraph.json for typed relations between pages, with localized node labels and localized page paths grouped under language keys where neededaliases.json for canonical naming and alias resolution, with alias maps grouped by language keylocales.json for supported locales, default locale, and localized page or metadata entrypoints
Frontend Rendering Contract
Because the /wiki directory is used as the content source for a frontend knowledge section, the agent MUST keep the wiki structurally suitable for rendering in a client UI.
The agent MUST prefer:
- Stable titles
- Predictable page categories
- Concise summaries
- Scannable section structure
- Low-noise prose
- Consistent related-links sections
- Glossary-friendly terminology
- Explicit overview pages for major topic areas
- Frontend-safe metadata fields
- Deterministic placement of pages within topic structure
The agent MUST avoid:
- Unstable naming
- Giant unstructured pages
- Excessive internal-only shorthand
- Unresolved placeholder text
- Duplicate pages with near-identical meaning
- Pages that make sense only with hidden context from private discussions
- Inconsistent summary formats
- Deeply nested navigation without overview pages
- Brittle formatting that assumes a specific renderer beyond Markdown basics
The agent SHOULD assume that page titles, summaries, tags, related links, and page types may be consumed directly by frontend code.
Wiki frontmatter is parsed as YAML under the strict OKF validator. Use canonical description for the one-line preview and structured sources mappings. Keep scalar descriptions concise and quote them whenever YAML punctuation could change their meaning.
If the repository renders wiki markdown directly in the browser as trusted repo-local content, the agent SHOULD also keep the emitted markdown inside that trust contract by avoiding raw HTML blocks, dangerous URL schemes, and inline DOM event-handler attributes so repo-level validation (e.g. via the Skill-owned trust validator) can stay the primary safety boundary.
Onboarding Requirement
The agent MUST treat newcomer comprehension as a first-class requirement.
For major subsystems or topic clusters, the agent SHOULD maintain at least one of the following:
- Overview page
- Getting-started page
- Glossary page
- Comparison page explaining how related concepts differ
- FAQ page for common newcomer confusions
The agent SHOULD prefer progressive disclosure:
- Short summary first
- Core concepts second
- Details after that
- Related pages at the end
The agent MUST NOT assume expert-only context in pages intended for general wiki navigation.
When writing for /wiki, the agent SHOULD resolve local shorthand, project-internal abbreviations, and conversation-derived assumptions unless those are already defined in /docs or in the wiki glossary.
Page Taxonomy
The agent SHOULD organize wiki pages into one or more of these types:
overviewgetting-startedconceptentityprocessdecisioncomparisonglossaryfaqstatustimeline
The agent SHOULD pick the smallest stable page type that matches the content.
The agent MUST prefer one concept per page rather than oversized mixed-topic pages.
The agent SHOULD create a new page only when:
- The concept deserves an independent node
- Synthesis spans multiple docs
- Navigation clarity improves
- The existing page would otherwise become too broad or unstable
- A frontend knowledge section benefits from a separate discoverable page
The agent SHOULD update an existing page instead of creating a new one when the new content clearly belongs to an existing node.
For frontend usability, the agent SHOULD ensure that important topic areas have an overview page before deep leaf pages multiply.
Page Contract
Each wiki page SHOULD include:
- Title
- Short summary
- Main synthesized content
- Related links
- Source provenance
- Freshness metadata if available
- Page type metadata suitable for frontend consumption
Each wiki page MUST begin with a short summary suitable for use as a frontend preview, card description, or search snippet.
This summary SHOULD:
- Fit within 1 to 3 short paragraphs
- Define the page topic clearly
- Avoid unresolved references
- Remain understandable to a newcomer
Recommended frontmatter shape:
---
type: concept
title: Example Concept
description: What this concept is and why it matters.
locale: en
canonical_page_id: example-concept
translation_status: source
available_locales:
- en
- ru
sources:
- resource: ../docs/path/to/source-a.en.md
- resource: ../docs/path/to/source-b.en.md
status: stable
audience: newcomer
tags:
- architecture
- runtime
related:
- Another Page
- Related Concept
---
Recommended mirrored-locale frontmatter extension:
---
type: concept
title: Пример концепции
description: Локализованное зеркало той же страницы.
locale: ru
canonical_page_id: example-concept
translation_of: ./example-concept.en.md
translation_status: mirrored-from-default
available_locales:
- en
- ru
sources:
- resource: ../docs/path/to/source-a.ru.md
- resource: ../docs/path/to/source-b.en.md
status: stable
audience: newcomer
related:
- Другая страница
---
Recommended body shape:
# Example Concept
## Summary
Concise synthesis of the concept.
## Key Points
- Point
- Point
## Details
Explanation of how the concept works.
## Related
- [[Another Page]]
- [[Related Concept]]
## Sources
- `docs/path/to/source-a.md`
- `docs/path/to/source-b.md`
The exact format MAY vary, but the page MUST remain readable by both humans and agents.
Glossary Requirement
The agent SHOULD maintain a glossary for recurring project terminology, especially when the docs contain abbreviations, domain-specific terms, overloaded concepts, or terms likely to confuse newcomers.
If a term appears across multiple pages and may confuse newcomers, the agent SHOULD either:
- Define it in a glossary page, or
- Link it consistently to a canonical concept page
The agent SHOULD prefer glossary-backed term stability over repeated ad hoc re-explanations.
Epistemic Rules
Provenance
For every nontrivial synthesized claim, the agent SHOULD preserve a traceable path back to /docs.
The agent MUST be able to answer, at least approximately, which source doc or docs justify a wiki statement.
Evidence Signals
Use verifiable signals only: structured source provenance, explicit lifecycle status, supersession links, locale parity, graph reachability, and concrete contradictions. Do not emit page-level compilation dates or subjective confidence scores; neither proves freshness or semantic correctness.
Supersession
If newer docs replace older semantics, the agent SHOULD mark prior wiki claims or pages as superseded rather than merely deleting historical context.
The agent SHOULD preserve traceability of supersession where feasible.
Suggested metadata:
status: supersededsuperseded_by: ...supersedes: ...
Contradictions
If two docs appear to conflict, the agent MUST NOT silently normalize them into a fake consensus.
The agent SHOULD:
- Identify the contradiction
- Prefer the stronger or newer authoritative source when justified
- Annotate the conflict when the evidence remains unresolved
- Mark the affected claim or page explicitly when uncertainty remains
Staleness
The agent SHOULD detect stale wiki content when source docs change, disappear, or imply different semantics.
Stale content SHOULD be updated, downgraded, marked stale, or marked superseded.
Evidence Discipline
The agent MUST NOT inflate sparse hints into strong conceptual claims.
Where the docs are insufficient, the wiki SHOULD remain conservative, explicit about uncertainty, and minimal in speculative interpolation.
Sync Pipeline
The agent MUST conceptually follow this pipeline.
Phase 1: Detect
The agent identifies relevant changes in /docs, including:
- Created files
- Modified files
- Deleted files
- Moved or renamed files
- Draft to active transitions
- Active to deprecated transitions
- Metadata changes relevant to authority or scope
- Glossary or terminology changes
- Top-level information architecture changes
If repository history or file diffs are available, the agent SHOULD use them.
If history is unavailable, the agent SHOULD infer likely changes from current state and user request.
Phase 2: Interpret
For each changed source, the agent SHOULD extract:
- Major topics
- Entities
- Concepts
- Decisions
- Terminology
- Relationships
- Deprecations
- Supersession signals
- Newcomer-relevant explanatory gaps
- Pages likely affected in
/wiki
The agent SHOULD determine whether the change:
- Updates an existing node
- Creates a new node
- Merges nodes
- Splits a node
- Invalidates or weakens prior claims
- Requires a new overview, glossary, comparison, or getting-started page
Phase 3: Compile
The agent updates /wiki incrementally.
Compilation MAY include:
- Creating new pages
- Updating existing pages
- Removing orphan pages
- Marking stale pages
- Marking superseded pages
- Updating source lists
- Updating backlinks
- Updating aliases
- Updating summaries
- Updating tags and related links
- Updating localized index entrypoints such as
index.en.md / index.<locale>.md
- Updating metadata stores such as
navigation.json, state.json, graph.json, aliases.json, or locales.json, including localized field objects inside those shared manifests
- Recording completed wiki delivery work in the project-level delivery history when repository state materially changes
The agent SHOULD prefer minimal sufficient edits over gratuitous rewrites.
Phase 4: Lint
After compile, the agent SHOULD validate the wiki for:
- Orphan pages
- Broken internal links
- Duplicate concepts
- Unresolved aliases
- Stale sources
- Contradictory claims
- Oversized pages
- Empty categories
- Low-signal pages
- Index drift
- Missing overview pages for large topic clusters
- Pages with poor summaries
- Excessive jargon density
- Undefined repeated terms
- Over-deep navigation chains
- Inconsistent category placement
- Leaf pages with no discoverable inbound path from the relevant
index.<locale>.md
Repository-local guard:
./.agents/skills/wiki-sync/scripts/audit-wiki-consolidation.sh
This guard fails on missing page role metadata, provenance, related-link blocks, locale mirrors, and navigation/graph reachability. It reports short pages and graph leaves as consolidation candidates instead of blocking useful writing by heuristic.
Phase 5: Consolidate
When requested or useful, the agent MAY run consolidation:
- Merge duplicates
- Strengthen summaries
- Compress repetitive pages
- Update supersession links
- Improve index structure
- Repair graph coherence
- Normalize page taxonomy
- Strengthen onboarding flow across topic clusters
Incremental vs Full Rebuild
Incremental Sync
Default mode SHOULD be incremental.
Incremental sync is preferred when:
- A small subset of docs changed
- Structure remains stable
- Page mapping remains clear
- Frontend-facing navigation structure remains mostly valid
Full Rebuild
The agent SHOULD choose or accept full rebuild when:
- Schema changed significantly
- Wiki drift is severe
- Page taxonomy changed
- Many docs moved or disappeared
- The user explicitly requests rebuild
- The current wiki appears unreliable
- Frontend navigation quality has degraded substantially
- Overview/glossary structure has become incoherent
During full rebuild, the agent MUST still preserve historical traceability when practical through source provenance, page state metadata, graph metadata, and the project-level delivery history.
Deletion and Deprecation Handling
If a source doc is deleted, the agent MUST determine whether the affected wiki content should:
- Be deleted
- Be marked stale
- Be marked deprecated
- Be marked superseded
- Be remapped to replacement docs
If a source doc is deprecated but still informative, the agent SHOULD preserve useful context while clearly marking its status.
The agent MUST NOT leave dead provenance references without marking them as stale or removed.
If a deleted or deprecated source affects newcomer understanding, the agent SHOULD ensure that overview or glossary pages remain coherent after the change.
Link and Graph Rules
The wiki SHOULD behave as a navigable semantic graph.
The agent SHOULD maintain:
- Internal links between related pages
- Aliases or canonical naming when needed
- Compact topic clusters
- A stable entry path from the relevant
index.<locale>.md to important nodes
- Discoverable progression from overview pages to leaf pages
- Related links suitable for frontend rendering
The agent SHOULD avoid:
- Isolated pages with no inbound or outbound relation
- Duplicate names for the same concept
- Excessive link spam
- Giant hub pages that collapse multiple unrelated concepts
If graph.json exists, the agent SHOULD keep it aligned with page relationships.
Naming Rules
The agent SHOULD prefer stable, explicit, concept-oriented names.
The agent SHOULD:
- Reuse existing canonical names where possible
- Resolve aliases carefully
- Avoid creating near-duplicate pages due to naming variation
- Prefer conceptual clarity over source file name mirroring
- Keep names understandable to newcomers
Examples:
- Good:
Execution Pipeline
- Good:
Configuration Layers
- Good:
Getting Started with Runtime Architecture
- Weaker:
notes-from-doc-2
- Weak:
misc
If ambiguity exists, the agent SHOULD anchor naming to the dominant concept expressed in /docs.
Before creating or renaming an owner page, the agent MUST answer four questions:
- Does the page own a domain, concept, mechanism, concrete subsystem, or product surface?
- What object will a reader reasonably expect to find under this title?
- Would the title remain true if the current pallet, package, or implementation changed?
- Do subsystem and mechanism each have enough independent content to justify separate pages, or should one page distinguish them internally?
The overview/ directory expresses an entrypoint role, not a naming schema. The agent MUST NOT mechanically prefix overview titles with a framework or product name. It SHOULD use a branded subsystem title only when the page actually owns that concrete subsystem; broader domain and concept pages retain semantic names such as Asset Identity, Governance, Staking, or Typed Observations.
Quality Thresholds
The agent SHOULD treat a wiki page as weak if it has one or more of these properties:
- No meaningful synthesis
- No provenance
- No relationships
- Duplicate concept overlap
- Stale unsupported claims
- Only trivial paraphrase of a single source
- Excessive size without structure
- Unresolved contradiction
- Poor newcomer-facing summary
- Unexplained jargon
- Unclear position in the navigation graph
Weak pages SHOULD be improved, merged, marked stale, converted into a different page type, or removed.
Manual Edits to /wiki
The repository MAY contain manually edited wiki pages.
If manual wiki editing exists, the agent MUST act conservatively.
Preferred policy:
- Generated pages remain generated
- Manual annotations live in explicitly marked sections
- The agent preserves marked manual sections when possible
- The agent does not overwrite clearly user-authored wiki material unless asked
Recommended markers for manual preservation:
<!-- BEGIN MANUAL -->
...
<!-- END MANUAL -->
If no such convention exists, the agent SHOULD avoid destructive rewrites unless forced by explicit request.
If the repository expects /wiki to be fully generated, the agent MAY rewrite pages freely within the generated contract.
Forced Commands Semantics
When the user or caller invokes this skill explicitly, interpret requests approximately as follows.
"sync wiki"
Run incremental detect -> interpret -> compile -> lint for affected areas.
"refresh wiki"
Run sync plus provenance, explicit lifecycle, summary, and related-link updates.
"rebuild wiki"
Recreate wiki artifacts from /docs comprehensively.
"lint wiki"
Do not rewrite content unless necessary for minimal repair; report or repair graph, provenance, navigation, and structural issues depending on context.
"consolidate wiki"
Merge duplicates, compress pages, improve graph coherence, update supersession, strengthen overview pages, and reduce onboarding friction.
"repair wiki"
Fix broken links, stale references, missing index entries, alias drift, missing summaries, weak taxonomy placement, and basic provenance gaps.
"regenerate page X"
Recompile only the targeted page or node if feasible.
"rebuild onboarding"
Prioritize overview, getting-started, glossary, comparison, and faq pages for major topic clusters.
The agent SHOULD infer the smallest reasonable scope from the user request.
Automatic Trigger Heuristics
In automatic operation, the agent SHOULD trigger sync when:
/docs/** changes materially- A doc moves between draft and active status
- A doc becomes deprecated or superseded
- Glossary or terminology changes
- Architecture or API docs change
- A top-level docs index changes
- The user asks a question whose answer would benefit from refreshed wiki structure
- Frontend-facing navigation would likely drift unless the wiki updates
The agent SHOULD avoid unnecessary sync when changes are purely cosmetic unless the repository explicitly wants style-only changes reflected in /wiki.
Doc Parsing Heuristics
When interpreting docs, the agent SHOULD prioritize:
- Headings
- Frontmatter
- Explicit status markers
- Definitions
- Normative statements
- Interface descriptions
- Process descriptions
- Decision rationales
- Deprecation markers
- Changelog-like sections
- Cross references
- Glossary definitions
- Onboarding-oriented explanatory sections
The agent SHOULD distinguish:
- Stable definitions
- Examples
- Speculative notes
- Deprecated behavior
- Implementation detail vs conceptual contract
- Expert detail vs newcomer-relevant surface explanation
Source Mapping Heuristics
The agent SHOULD maintain a many-to-many mapping between /docs and /wiki.
One doc MAY influence multiple wiki pages.
One wiki page MAY synthesize multiple docs.
The agent SHOULD maintain source-to-page awareness either explicitly or implicitly.
If metadata storage exists, the agent SHOULD store something equivalent to:
- Doc -> affected wiki pages
- Wiki page -> supporting docs
- Alias -> canonical page
- Page -> explicit lifecycle and provenance state
- Page -> taxonomy role
- Page -> related pages
- Page -> newcomer relevance or audience level
Delivery-History Rules
The agent MUST NOT create or update wiki/log.<locale>.md files unless the repository explicitly reintroduces wiki-local logs.
For this repository, meaningful completed wiki work belongs in CHANGELOG.md, while open wiki work belongs in BACKLOG.md only when it remains a concrete unfinished deliverable.
A delivery-history entry SHOULD include impacted areas and concise rationale without duplicating metadata already stored in /wiki/_meta.
Failure Behavior
If sync cannot be completed fully, the agent MUST prefer partial truthful progress over pretending completion.
The agent SHOULD:
- Update what can be updated safely
- Mark uncertain areas
- Note unresolved contradictions or missing evidence
- Avoid fabricated freshness or evidence strength
- Preserve frontend-stable artifacts where possible
- Avoid destructive churn when evidence is insufficient
The agent MUST explicitly acknowledge when:
- Sources are missing
- Provenance is incomplete
- Rebuild scope is partial
- Manual wiki content prevented safe overwrite
- Contradictions remain unresolved
- Frontend-facing navigation remains partially degraded
Interaction Contract
When using this skill in an interactive workflow, the agent SHOULD:
- State whether it is performing incremental sync, rebuild, lint, repair, or consolidation
- Mention the main affected areas
- Surface contradictions or drift early
- Report what changed in concise operational terms
- Mention if onboarding/navigation pages were affected
- Avoid verbose process narration
The agent SHOULD not ask unnecessary clarifying questions if it can proceed safely from repository state and user request.
Safe Defaults
Unless repository conventions explicitly say otherwise, the agent MUST default to:
/docs authoritative/wiki generated derivative- Incremental sync first
- Provenance preserved
- Contradictions surfaced
- Summaries concise
- Glossary encouraged
- Index compact
- No wiki-local mutation logs by default
- No
/docs mutations
- No silent deletion of meaningful history
- No insider-only writing style for general wiki pages
Minimal Operational Checklist
On each sync, the agent SHOULD attempt to ensure:
- Changed docs identified
- Affected wiki pages identified
- Pages updated or created
- Stale or superseded pages marked
index.<locale>.md refreshed for the affected locales- Project-level delivery history updated when repository state materially changes
- Broken links checked
- Duplicate concepts checked
- Provenance preserved
- Contradictions handled honestly
- Summaries suitable for frontend rendering
- Large topic areas retain overview discoverability
- Recurring terms remain defined or linked canonically
Preferred Output Style for Generated Wiki
The agent SHOULD write wiki content in a style that is:
- Compact
- Explicit
- Navigable
- Concept-first
- Low on filler
- High on structural clarity
- Readable by newcomers
- Stable under frontend rendering
The wiki SHOULD optimize for future agent and human reuse, not literary flourish.
The agent SHOULD prefer:
- Short opening summaries
- Crisp headings
- Clear distinctions
- Explicit terminology
- Stable linkable sections
The agent SHOULD avoid:
- Unexplained project slang
- Unnecessary rhetorical flourish
- Dense insider compression without definitions
- Bloated paragraphs
- Weakly justified abstraction jumps
Upgrade Path
This skill MAY evolve in maturity.
v0
- Create/update summary pages
- Maintain index and metadata
v1
- Add backlinks
- Add page taxonomy
- Add source mapping
v2
- Add supersession
- Add contradiction handling
- Add staleness handling
- Add frontend summary discipline
v3
- Add typed graph artifacts
- Add alias resolution
- Add consolidation passes
- Add stronger lint and repair behavior
- Add onboarding-quality audits
The agent SHOULD use the highest maturity level supported by the repository context without forcing unnecessary complexity.
Final Rule
The agent MUST treat wiki synchronization as semantic compilation, not mere summarization.
The objective is not to duplicate /docs.
The objective is to maintain a compact, truthful, navigable, provenance-aware, cross-linked /wiki that stays aligned with /docs while also serving as a frontend-renderable onboarding and reference layer for newcomers to the project.
