mycoknowledge-placement-doctrinelisted

Apply when deciding WHERE to record knowledge, instructions, or context in the Myco project — even if the user hasn't explicitly asked about documentation strategy. Covers five surfaces: AGENTS.md (durable agent operating rules and architectural invariants only), SKILL.md files (codified project procedures with steps and examples), inline code comments (behavioral invariants and HOW the code works — never historical narrative), the Myco vault (decisions, rationale, incidents, tradeoffs), and user-facing docs (README, CHANGELOG, docs/, marketing site — user mental model only, never internal mechanics). The wrong surface creates knowledge rot: implementation details in user docs confuse users, historical narrative in code comments becomes lies as code evolves, behavioral invariants buried only in the vault leave developers guessing at the point of action. Use this skill when writing any new knowledge, reviewing a PR for doc discipline, or auditing existing content for surface violations.
goondocks-co/myco · ★ 13 · AI & Automation · score 79

Install: claude install-skill goondocks-co/myco

# Myco Knowledge Placement Doctrine Myco organizes project knowledge across five distinct surfaces, each with a specific role and audience. Placing knowledge on the wrong surface creates knowledge rot — code comments that lie as code evolves, user docs that confuse with implementation internals, vault decisions that never reach developers at the point of action. This skill defines which surface is correct for each type of knowledge and how to detect violations during review. ## Prerequisites Before placing any knowledge, answer three questions: - **Type:** Is this an operating rule? A procedure? A behavioral invariant? A decision rationale? User-facing guidance? - **Audience:** Is this for an AI agent? A developer reading code? A user installing or configuring Myco? A future architect? - **Lifespan:** Is this durable (stable across releases)? Behavioral (true as long as the code exists)? Historical (true at a point in time)? The answers determine the surface. ## Procedure A: Agent Operating Rules → AGENTS.md AGENTS.md is reserved for **durable architectural patterns** that AI agents need to operate correctly across all work in this project. These are standing rules that survive across sessions, PRs, and releases. **What belongs in AGENTS.md:** - Discovery rules: how to find the right files, which patterns to search for - Action rules: invariants an agent must uphold when making any change - Architectural invariants that are always true and guide how to act - The user-o