# Beejones Protected Container Documentation And Adrs > Documentation And ADRs Skill - Skill: `tomevault-io/beejones-protected-container-documentation-and-adrs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/beejones-protected-container-documentation-and-adrs` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/beejones-protected-container-documentation-and-adrs/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/beejones-protected-container-documentation-and-adrs --- # Documentation And ADRs Skill ## Principles Document the why, the contract, and the operating rules. Code shows what exists; docs should explain the constraints future humans and agents must preserve. Repo rule: when modifying a module, review the corresponding `docs//` area for missing, duplicate, stale, or broken documentation. Each major doc should start with a principles section. ## When To Use - Changing public API behavior, strategy JSON contracts, data-source behavior, analyzer/optimizer workflows, or deployment behavior. - Adding or modifying docs under `docs/`, `planning/`, `analysis/`, or `AGENT.md`. - Making a durable architecture decision or rejecting meaningful alternatives. - Repeating the same explanation in chat or code review. - Updating custom skills, instructions, agents, or workflow guidance. ## Documentation Types ### Module Docs Use for durable behavior and operating principles. Put them under `docs//` when the module has a docs area. Include: - Principles guarded by the code. - Public workflows or contracts. - Important boundaries and data flow. - Validation commands or evidence requirements. - Links to related docs without duplication. ### Planning Files Use `planning/` for active implementation plans. Completed plans move to `archive/planning/` with an `_ARCHIVED` suffix. ### Analysis Reports Use `analysis/` for evidence-heavy investigation, optimizer/analyzer validation, or strategy adoption reasoning that should persist. ### ADR-Style Notes Use ADR-style sections when a decision is expensive to reverse: - Status. - Date. - Context. - Decision. - Alternatives considered. - Consequences. This repo does not require a separate ADR system before writing useful rationale. Prefer a small durable note in the most relevant docs location. ## Procedure ### Step 1 - Identify Documentation Impact Ask: - Did behavior, workflow, setup, API shape, strategy contract, or validation change? - Would a future agent need this context to avoid re-deciding or breaking it? - Is there an existing doc that should be updated instead of creating a new one? ### Step 2 - Update The Right Artifact - Module behavior -> `docs//`. - Active work breakdown -> `planning/`. - Evidence or decision report -> `analysis/`. - Agent operating rule -> `AGENT.md` or `.github/skills//SKILL.md`. - User-facing README/setup behavior -> `README.md` or relevant setup docs. Avoid duplicate docs. Prefer updating the canonical doc and linking to it. ### Step 3 - Write Useful Content - Start major docs with principles. - Explain why, not just what. - Include constraints and rejected alternatives when they matter. - Include exact commands for validation when future users need them. - Use concise examples only when they prevent ambiguity. - Remove stale or commented-out content instead of preserving it. ### Step 4 - Validate Docs Check links, command accuracy, file paths, and consistency with code. If docs mention tests or scripts, ensure commands match repo conventions. ## Red Flags - New public behavior with no docs update. - Docs that duplicate another file and will drift. - Comments explaining obvious code instead of intent. - TODOs left where a small fix would solve the issue. - Planning files left active after all tasks are complete. - Strategy or API contract changes described only in chat. - AGENT.md grows with detailed workflow content that belongs in a skill. ## Exit Criteria - [ ] Relevant docs were reviewed for the changed module. - [ ] New or changed behavior is documented in the canonical location. - [ ] Duplicates, stale statements, and broken links were fixed or reported. - [ ] Durable decisions include rationale and consequences. - [ ] Validation commands in docs are accurate. --- > Source: [beejones/protected-container](https://github.com/beejones/protected-container) — distributed by [TomeVault](https://tomevault.io).