perhapsspy/project-legibility

Use for agent work with clear excess-cost risk: broad or unpredictable logs and diffs, browser/UI loops, costly execution/retry loops and progress observation even with small output, costly or repeated delegation, or repeated compaction. Guides bounded execution and observation, preflight output limits, bounded delegation, evidence reuse, and compact checkpoints. Skip routine edits and direct answers. Routine test runs alone are not a trigger.

Use when creating, editing, or reviewing AGENTS.md, agents.md, CLAUDE.md, Copilot instructions, Cursor rules, or any always-read repository instruction file. Keep persistent agent instructions small, durable, non-duplicative, and action-oriented; classify content that belongs in commands, onboarding, reference docs, handoff state, enforcement, or removal instead of preserving it in always-read files.

Use when an interactive flow is laggy, stale, or race-prone because user intent, source state, derived presentation, async IO, scheduling, or background work are mixed. Keep source state prompt, protect the urgent interaction path, and admit async or presentation results only through a freshness-owning boundary.

Resume, handoff, and long-running repo work by keeping durable context across threads or agents: task briefs, logs, and reusable reference notes.

Audit scattered repository docs and notes, then move only the right working context into the project-context structure.

Use when product meaning or implementation-planning direction is materially open before solution structure is settled, including early direction for a new feature, reuse choices, temporary implementations, or another materially consequential product or implementation-planning choice. Choose a bounded provisional direction from user/domain purpose, locked decisions, explicit constraints, authority, current evidence, and observable success. Do not use for settled code structure, implementation execution, source discovery, or document editing.

Use for read-only source-of-truth audits: identify the current code, API, config, doc, or behavior to follow; compare a proposed, migrated, ported, or current change against it; and report evidence, mismatches, unresolved decisions, and owner-level recommendations.

Use for code generation, feature work, bug fixes, refactoring, and code review when a change creates or reshapes a multi-step flow, state lifecycle, side-effect or decision ownership, cross-unit composition, or boundary contract. Also use it when an existing structural problem makes those elements hard to trace or verify. Structural change is optional. Mechanical edits, throwaway experiments, and coherent local changes stay with their current owner and focused verification.

Use by default whenever creating, revising, reviewing, or finalizing human-authored documentation whose source meaning is settled, including documentation changed within another task. Apply from first draft through final review to keep one direct current state, clear reader routes and ownership, and remove rejected decisions that survive as negation or defensive prose. Skip prose-free mechanical edits, unresolved meaning, append-only history, generated artifacts, pure translation or localization, and always-read instruction design.