Project documentation hygiene

Project Documentation Hygiene

Goal

Treat Markdown documents as part of the project, not part of any AI assistant.

Whenever a project is created, updated, archived, or cleaned up, organize its documentation so it remains understandable and reusable regardless of whether future work is done with ChatGPT, Claude, Codex, Gemini, or another AI assistant.

Principles

1. Documentation belongs to the repository, not the AI tool.
2. Every important design decision should exist in Markdown.
3. AI conversations are temporary; project documentation is permanent.
4. A new AI assistant should be able to understand the project by reading the repository alone.
5. Avoid AI-specific wording such as "Claude Project", "Codex Session", or "ChatGPT Memory" inside project documentation whenever possible.

Operating Modes

Use the mode implied by the user's request.

Audit mode

Use audit mode when the user asks to audit, inspect, review, report, assess, check, or diagnose documentation hygiene.

In audit mode:

• inspect the project documentation
• identify gaps, stale files, duplicated material, assistant-specific wording, and missing durable decisions
• produce prioritized findings and recommended edits
• do not modify project files unless the user also asks for fixes

Apply mode

Use apply mode when the user asks to create, update, organize, clean up, normalize, fix, improve, apply, or maintain project documentation.

In apply mode, do not stop at an audit. Make the documentation changes directly when they are in scope and safe:

• create missing documentation directories and Markdown files
• update README.md with project goal, motivation, current status, quick start, and repository structure
• create or update docs/overview.md, docs/architecture.md, docs/roadmap.md, docs/decisions.md, docs/experiments.md, docs/setup.md, docs/prompts.md, and docs/references.md
• move durable design rationale out of assistant-specific files into repository-owned Markdown
• replace avoidable assistant-specific wording with platform-neutral wording
• consolidate duplicated Markdown sections when the surviving location is clear
• archive outdated roadmaps, designs, and completed milestone notes into docs/archive/
• update cross-links so the documentation remains navigable

For a broad workspace containing multiple projects, apply safe additive edits by default only when the user explicitly asks for broad fixes. Otherwise, produce an audit report first and recommend a project order.

Plan-then-apply mode

Use plan-then-apply mode when the requested changes are broad, cross multiple repositories, involve moving files, or could overwrite substantial existing documentation.

In plan-then-apply mode:

1. Inspect the current documentation state.
2. Produce a concise edit plan listing files to create, update, move, archive, or delete.
3. Apply safe additive edits immediately when the user's request clearly authorizes them.
4. Pause before destructive or ambiguous edits, especially deletion, overwriting, or moving files whose information may not be preserved elsewhere.
5. After edits, verify changed files and report the exact paths changed.

Standard Documentation Structure

Use this structure when creating or normalizing project documentation:

project/
README.md
docs/
    overview.md
    architecture.md
    roadmap.md
    decisions.md
    experiments.md
    setup.md
    prompts.md
    references.md

Optional supporting directories:

docs/
    meeting-notes/
    designs/
    figures/
    archive/

File Purposes

README.md

High-level overview.

Include:

• project goal
• motivation
• current status
• quick start
• repository structure

docs/overview.md

Explain:

• problem
• objectives
• scope
• non-goals

docs/architecture.md

Describe:

• overall workflow
• components
• data flow
• software structure
• experimental pipeline

docs/roadmap.md

Maintain:

• completed milestones
• current priorities
• future work
• known limitations

docs/decisions.md

Record major decisions.

For each decision include:

• date
• context
• options considered
• final decision
• rationale

Never rely on chat history for these.

docs/experiments.md

Log important experiments.

Include:

• hypothesis
• method
• results
• interpretation
• next steps

Avoid storing only successful experiments.

docs/setup.md

Document everything required to reproduce the project.

Examples:

• dependencies
• installation
• environment variables
• hardware
• cloud resources
• datasets

docs/prompts.md

Store reusable prompts only.

Do not include conversation history.

Instead, document:

• prompt purpose
• expected inputs
• expected outputs
• examples

docs/references.md

Maintain:

• papers
• datasets
• repositories
• APIs
• useful links

Cleanup Rules

Before archiving or deleting a project:

Keep:

• README
• architecture
• roadmap
• decisions
• experiment summaries
• reusable prompts
• references

Archive:

• completed milestones
• outdated designs
• previous roadmaps

Move archived material into:

docs/archive/

Delete:

• scratch notes
• temporary brainstorming
• duplicated content
• AI-generated intermediate drafts
• obsolete TODO lists

Only delete files whose information already exists elsewhere.

Bulk Edit Rules

Bulk edits are allowed when the user asks for documentation cleanup, normalization, maintenance, or fixes. Treat them as repository documentation work, not as an audit-only task.

Before bulk edits:

• identify the project root or bounded set of project roots
• check the current Git status when the target is a Git repository
• avoid mixing unrelated user changes into the documentation update
• prefer additive Markdown files and cross-links over large rewrites
• preserve original meaning, dates, decisions, and evidence

During bulk edits:

• create missing docs/ directories and standard Markdown files where useful
• keep each major topic in the correct file instead of duplicating it across README and docs
• move durable content from assistant-specific files into neutral project docs
• leave platform-specific operational files in place when tools need them
• add a short pointer from assistant-specific files to the canonical repository docs when useful
• use docs/archive/ for outdated but potentially useful material
• keep reusable prompts in docs/prompts.md, not in chat transcripts
• keep references in docs/references.md, not scattered across scratch notes

After bulk edits:

• verify that Markdown files answer the documentation quality checklist
• verify that important links and referenced paths still make sense
• summarize files created, files updated, files moved or archived, and files intentionally left unchanged
• if the repository uses Git, report whether the working tree is now dirty and list changed files

Do not delete project files unless all of these are true:

1. the user explicitly requested cleanup or deletion,
2. the file is clearly scratch, temporary, duplicated, or obsolete,
3. its durable information already exists in another Markdown file or is intentionally not worth preserving,
4. the deletion scope is reported clearly.

Documentation Quality Checklist

Each Markdown file should answer:

• What is this?
• Why does it exist?
• What is the current state?
• What should someone do next?

If the answer requires opening an old AI conversation, improve the documentation.

AI Independence Test

Assume the repository is opened by someone who has never seen any previous AI chats.

They should be able to understand:

• project goals
• architecture
• design rationale
• experimental history
• current progress
• next priorities

using only the Markdown documentation.

If not, update the documentation before considering the project complete.

Final Rule

Documentation is a long-term project asset.

AI projects, chat histories, and assistant-specific memory are temporary.

Always preserve knowledge in the repository rather than in the AI platform.