miaodx/intuitive-flow/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.

For plan and task-state placement, follow plan selection. Preserve the repo's existing canonical plans and lifecycle layout. When adopting Intuitive defaults, use a flat plan directory and keep current execution state in the task-owned resume surface. A plan dashboard is an agent navigation aid.

This compact entrypoint preserves full mode-specific guidance in detailed guidance. 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

Name the selected mode in one sentence before non-trivial audits or edits, and mention a better owner only when one exists.

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. Once routing, truth, and links are correct, stop; wording polish is not the goal.