intuitive-doc

name	intuitive-doc
description	Create and maintain an intuitive human documentation surface for AI-agent-developed repos. Use when humans should only need README.md, ARCHITECTURE.md, STATUS.md, and docs/human/** while planning logs, generated docs, retrospectives, ADR detail, and implementation evidence stay in AI-agent-only folders.

Intuitive Doc

Use this skill to keep the human-facing documentation surface small, current, and reviewable. The default human surface is:

• README.md;
• ARCHITECTURE.md;
• STATUS.md;
• docs/human/**.

Planning logs, generated evidence, retrospectives, ADR detail, execution artifacts, scratch notes, and agent-only runbooks should stay outside the human surface unless a human doc intentionally promotes them.

Plan contracts use the fixed flat surface docs/plans/<slug>.md. Put lifecycle in the plan's ## Plan Ledger and current execution state in docs/status/active/, not in plan lifecycle directories or one-off prompt files. Treat docs/plans/README.md, when present, as the plan dashboard rather than a human-facing project manual.

This compact entrypoint preserves full mode-specific guidance in references/detailed-guidance.md. Read it for detailed audit/update/cleanup criteria, perspective levels, documentation standards, or full output format.

When To Activate

Use this skill when:

• root docs drift from current code, commands, or active plans;
• humans need a concise orientation after AI-heavy development;
• implementation changed public behavior, command surfaces, setup, architecture, or status;
• generated/planning/agent evidence has leaked into human docs;
• the user asks for documentation cleanup, human docs, README/architecture/status updates, or post-implementation doc alignment.

Modes

Mode	Use when	Output	Redirect when
Audit	The user asks whether docs are current, bloated, or misplaced.	Findings, recommended changes, parked items, verification.	The issue is agent guidance, tests, or code layout.
Update	Current behavior, commands, architecture, or status changed.	Focused doc edits tied to current source evidence.	The requested change is only planning/evidence archival.
Cleanup	Human docs contain stale, duplicated, or over-detailed material.	Moved, archived, shortened, or removed docs with links preserved.	The material belongs in agent guidance or execution plans.
Guard	A proposed doc change needs placement review.	Placement decision and reason.	The user already selected the doc target and asks to edit.

For non-trivial runs, state Selected mode:, Why:, and Redirect: before auditing or editing. For tiny doc edits, one sentence can carry the same information. Add a final Mode note: only when manual invocation, ambiguity, or a better owner matters.

Human Surface Rules

• README.md orients and points to the current map; it should not become a manual.
• ARCHITECTURE.md owns subsystem contracts, data flow, extension points, and proof boundaries.
• STATUS.md owns current state, supported commands, next maintenance focus, and known blockers.
• docs/human/** owns human-facing detail that would bloat root docs.
• Agent runbooks belong in docs/agents/** or skill references unless humans need them as project truth.

Output

For audit/report-only work, return:

Human docs status:
Findings:
Recommended changes:
Parked items:
Verification:

For edits, report changed files, the current-truth source used, verification run, and any docs intentionally left unchanged.

Stop Conditions

Stop when the small human surface lets a human answer what the project is, how to run or verify it, what is current, what changed, and where deeper detail lives. Do not keep polishing wording once routing, truth, and links are correct.