squeezelite-esp32/documentation/agents/document_gardening.md

Document Gardening Playbook

Use document gardening to keep agent-facing and implementation docs current, lint-clean, and actionable during active development.

What It Includes

• fix markdown lint/style issues
• refresh stale links and pointers
• sync status boards and handoff logs
• archive completed short-term goals
• remove drift between policy docs and current workflow

What It Does Not Include

• changing product behavior
• changing source code unless explicitly requested
• rewriting long-form architecture without a scoped request

CI Flow Integration

Use the lane split from documentation/agents/ci_lane_contract.md.

1. Upstream GitHub lane:
   • run markdown/doc lint checks
   • validate docs can be rendered and linked
   • fail fast on malformed docs
2. Local LXD lane:
   • run agent-driven gardening tasks
   • update short-term coordination docs
   • produce handoff notes for next session

Standard Gardening Task

1. Read:
   • AGENTS.md
   • documentation/agents/README.md
   • documentation/short-term/coordination/workstream_board.md
2. Lint target docs.
3. Apply minimal, scoped fixes.
4. Re-run lint.
5. Update handoff/status docs if task context changed.
6. Report:
   • files touched
   • lint evidence
   • residual risks

Baseline Commands

npx -y markdownlint-cli2 "documentation/**/*.md" AGENTS.md

Optional targeted run:

npx -y markdownlint-cli2 \
  AGENTS.md \
  documentation/agents/**/*.md \
  documentation/short-term/**/*.md

Prompt Template

Use this when assigning gardening in CI/LXD:

Run a document gardening pass for the current goal.
Scope: AGENTS.md, documentation/agents/, documentation/short-term/.
Requirements:
1) lint markdown and fix only in-scope issues,
2) keep behavior/policy intent unchanged,
3) update workstream board + handoff log if status changed,
4) report lint before/after and residual issues.

Related Active Goal

• documentation/short-term/active/GOAL-003-agent-doc-lint-ci.md tracks short-term implementation for agent-driven doc linting in CI/CD.