doc torn — Enhancing AI agents with structured…

Pitch

Description

Comments

About this project

The doc-torn project empowers AI coding agents to maintain structured documentation in sync with the code. By implementing a clear hierarchy and a comprehensive dependency matrix, it enhances code understanding and documentation consistency. Ideal for teams looking to streamline their development processes.

doc-torn is a project designed to enhance the documentation skills of AI coding agents, ensuring that documentation is consistently structured and in sync with the corresponding code. This repository establishes a hierarchical documentation framework (L0 → L1 → L2 → L3) along with a clear dependency matrix among various features.

Key Skills

Structured Documentation: Manages the core lifecycle from initialization to updates, adhering to the L0-L3 hierarchy.
Doc-Driven Exploration: Promotes a documentation-first approach, encouraging thorough reading of documents before engaging with the code.
Documentation Consistency: Conducts comprehensive audits of all documentation against the codebase, with capabilities to auto-fix discrepancies.

Tool Overview

doc-torn-scan: A Go binary tool that enables iterative documentation processes on a feature-by-feature basis. It is utilized for tree scanning, scaffold generation, and meta-document creation.

Usage

The capabilities of doc-torn are leveraged based on specific tasks:

Task	Load Skill	Follow-up Action
Documenting a new codebase	`structured-documentation` (init mode)	Engages in the doc-torn-scan workflow iteratively
Preparing for a new feature implementation	`doc-driven-exploration`	Reviews existing documentation before code engagement
Finalizing documentation post-feature completion	`structured-documentation` (update mode)	Synchronizes documentation, recalculates dependencies, and updates AGENTS.md
Regular audits or pre-release checks	`documentation-consistency`	Conducts thorough audits and auto-fixes discrepancies

Documentation Hierarchy (L0 → L3)

The project adopts a structured documentation hierarchy that separates concerns by abstraction level, facilitating a tailored reading experience for different stakeholders:

Level	File	Reader Type	Purpose
L0	`docs/README.md`	General Audience	Provides an overview, architecture diagram, and feature list.
L1	`docs/features/<name>/README.md`	Feature Developers	Details feature objectives, logic, dependencies, APIs, and key files.
L2	`docs/features/<name>/sub-features/*.md`	Implementers	Contains details on edge cases, business rules, and sub-flows.
L3	`docs/features/<name>/implementation/*.md`	Maintainers	Discusses technical decisions, rationale, and trade-offs.

This layered approach ensures that users can access only the information pertinent to their role, from high-level overviews to in-depth analyses.

Repository Structure

The following structure is maintained:

skills/
  structured-documentation/
  doc-driven-exploration/
  documentation-consistency/
tools/
  doc-torn-scan/
examples/
  AGENTS.md
  hooks/

Overall, doc-torn equips AI coding agents with the essential skills for maintaining high-quality, accurate documentation that evolves with the development lifecycle, streamlining the programming workflow and enhancing collaboration.