Skip to content

docs.md

Latest commit

 

History

History
73 lines (54 loc) · 2.52 KB

docs.md

File metadata and controls

73 lines (54 loc) · 2.52 KB

/docs Workflow

Version: 1.7.10

The /docs workflow creates, reviews, and publishes technical documentation for PARA projects. It follows an internal-first approach: always create in the project's docs/ directory, then promote to repo/docs/ when ready.

Commands

/docs [project-name] [action]
Action Description
new Analyze project and create appropriate docs
review Audit existing docs for freshness and accuracy
update Update specific doc to reflect current code
publish Promote selected docs from docs/ to repo/docs/

Doc Locations

Projects/[project-name]/
├── docs/               ← DEFAULT: All docs created here (internal)
│   └── README.md         ← Doc Index (required)
│
└── repo/docs/          ← PUBLISH ONLY: Promoted from docs/
Criteria docs/ (default) repo/docs/ (after publish)
Created Always — /docs new Only via /docs publish
Audience Internal team, AI agent Developer, contributor
Git ❌ Not tracked ✅ Tracked in repo
Language User's preferences.language Repo's language

Doc Index

Every docs/ directory MUST have a README.md index — a ~10 line table listing all docs. The agent reads this single file instead of scanning the directory, saving tokens.

/docs new auto-creates this file if it doesn't exist.

/docs new Flow

  1. Agent Indices Pre-flight (v1.7.10) — Runs a Soft Dump script that force-loads .agents/rules.md and .agents/skills.md into context (Anti-Cognitive-Bypass).
  2. Read project.md (goal, tech stack, status)
  3. Scan source code (structure, entry points)
  4. Classify project type → recommend appropriate docs
  5. Read Doc Index → skip docs that already exist
  6. Present doc plan → wait for user confirmation
  7. Create docs based on actual code, not assumptions
  8. Create/update Doc Index (README.md)
  9. Log in session

/docs publish Flow

  1. Read Doc Index to list available docs
  2. User selects which docs to publish
  3. Adapt for repo audience:
    • Detect repo language → translate if needed
    • Condense to 40-100 lines
    • Fix workspace-specific paths
  4. Copy to repo/docs/
  5. Log in session

Related

Added in v1.4.10. Updated in v1.7.10 (Cognitive Bypass Fix — Soft Dump payload in Step 0).