Cluedoc is an "Agent Skill" designed to maintain human-readable technical documentation in software projects where coding agents accelerate development beyond the pace of human manual oversight. It treats a software system as a hierarchical collection of features rather than a collection of files, enforcing a documentation standard that mimics academic papers to ensure conceptual clarity.

Core Methodology

The system operates on the principle that documentation must be a living artifact synchronized with code changes. It avoids the drift associated with static READMEs or traditional reference generators (like Doxygen or JSDoc) by delegating maintenance to the coding agent itself.

1. The Capability Tree and Feature Hierarchy
Cluedoc organizes documentation into a .cluedoc/ directory at the project root. The architecture is defined by:

• The Feature Unit: Documentation is modularized by feature, not by source file structure.
• The Tree Structure: Features exist in a hierarchy where high-level capabilities contain sub-feature papers.
• The Six-Section Format: Every paper must adhere to a rigid academic structure: Hero visual, Abstract, Introduction, Related Work, Description, and Conclusion. This enforces a consistent "mental model" for any reader navigating the codebase.

2. Progressive Synchronization
Cluedoc employs a bidirectional synchronization strategy to ensure documentation remains relevant as the codebase evolves:

• Upward Traversal: Upon a code change, the agent identifies the parent feature by mapping the current module to its callers.
• Downward Traversal: The agent identifies downstream dependencies (callees) to determine if collaborators require documentation updates.
• Decoupling Prose from Implementation: To ensure longevity, papers strictly exclude code snippets. Instead, they use a sources metadata field in the YAML frontmatter to link specific files to conceptual modules.

3. Citation Graph and Navigation
The "Related Work" section functions as a bibliography, creating a citation graph. This enables non-linear traversal of the system. Cluedoc further provides a "Reading Guide" feature, which utilizes a pathing algorithm to suggest a sequence of papers:
$S_{guide} = \{P_1, P_2, \dots, P_n\}$
where $P$ represents the optimal set of documents required to explain a specific query, prioritized by relevance and dependency order within the tree.

Technical Implementation

Cluedoc functions via an Agent Skills specification. It is triggered through a CLI (/cluedoc) that integrates into the agent’s instructions. Unlike background daemons or git hooks, it operates "in the loop" of the agent’s session. The agent maintains the documentation by:

1. Refactoring: Creating, splitting, or deleting folders as feature boundaries change.
2. Maintaining Integrity: Resolving broken cross-links in real-time.
3. Visualization: Prioritizing Mermaid diagrams and terminal graphics over text to facilitate rapid comprehension, following the axiom that visual structure is superior to "walls of prose."

Ultimately, Cluedoc transforms a repository into a searchable, academic-style corpus, allowing developers to treat complex software systems as structured knowledge rather than raw, unorganized code.