Intuitive Doc

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/.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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MiaoDX
• Source: MiaoDX/intuitive-flow
• License: MIT

Install and usage instructions live in the source repository linked above.