Loam::auditing Guidance

Agent Markdown Improver

Audit, evaluate, and improve agent guidance markdown files across a codebase so future agent sessions have better project context.

This skill can write to guidance files. After presenting a quality report, it updates AGENTS.md, CLAUDE.md, or .claude.local.md with targeted improvements and direct stale/duplicate pruning.

Workflow

Phase 1: Discovery

Find all guidance files in the repository:

find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".claude.local.md" \) 2>/dev/null | head -50

File Types & Locations:

Default update rule: AGENTS.md is the canonical guidance file — all shared guidance goes there. CLAUDE.md must exist but contains only @AGENTS.md (Claude Code's import syntax). Never write content to CLAUDE.md — it is an import shim, not a content file. Use .claude.local.md for personal preferences only. If you find a CLAUDE.md with content beyond @AGENTS.md, flag it as drift (see Phase 1b below).

Phase 1b: CLAUDE.md Shim Check

If a CLAUDE.md was found in Phase 1, read it and verify it contains only @AGENTS.md (Claude Code's import syntax). This is the canonical pattern:

• AGENTS.md = canonical shared guidance (the single source of truth)
• CLAUDE.md = thin import shim containing exactly one line: @AGENTS.md
• .claude.local.md = personal/local overrides (gitignored)
• .claude/rules/ = Claude-specific path-scoped rules (if needed)

If CLAUDE.md has content beyond @AGENTS.md:

1. Check if the extra content is unique and valuable
2. If yes: propose moving it to AGENTS.md (if shared) or .claude/rules/ (if Claude-specific and path-scoped) or .claude.local.md (if personal)
3. Then propose collapsing CLAUDE.md back to @AGENTS.md only
4. Flag this as drift in the quality report

If CLAUDE.md is already just @AGENTS.md: no action needed, it's compliant.

Phase 1c: Design-system file cross-reference

Check whether a DESIGN.md exists at the repo root (case-insensitive; also check .stitch/DESIGN.md). If one exists, verify AGENTS.md references it (grep for DESIGN.md in the guidance file).

• If DESIGN.md exists and AGENTS.md references it: no action — compliant.
• If DESIGN.md exists but AGENTS.md does not reference it: flag as a cross-reference gap in the Phase 3 quality report (under "Non-Obvious Patterns"). Do not auto-propose the fix text — surface the gap and let the user decide what to add.
• If no DESIGN.md exists: no action — the check is conditional on the file being present.

Phase 1d: Memory map ensure/regenerate

Only when the workspace has a memory root: a wiki/ directory holding SCHEMA.md, index.md, or log.md — or those files at the workspace root itself, which the runtime also accepts. Workspaces without one skip this phase; the block is not applicable and its absence is not a defect.

Loam owns a fenced region inside root AGENTS.md that lists the durable memory page slugs, so an agent reading the guidance file learns the memory exists without paying for index.md every session. See references/templates.md "Template: Memory (Loam memory map)" for the exact marker strings and the generation rules — that template is the single source of truth for both, here and in loam::scaffolding-wiki.

With the native runtime (preferred — it is the same generator):

<native-runtime-command> lint --only guidance "$WORKSPACE_ROOT"         # report
<native-runtime-command> lint --only guidance --fix "$WORKSPACE_ROOT"   # insert or regenerate

--fix inserts the ## Memory section when the markers are absent — creating AGENTS.md if the workspace has none — and regenerates the region in place when it is stale. It preserves every byte outside the markers and never touches CLAUDE.md. Re-run the report form afterwards; it should be silent.

Without the native runtime (graceful fallback — no runtime dependency, and nothing invented): build the region yourself from the page tree and edit it in.

ls wiki/topics wiki/entities wiki/concepts wiki/analyses 2>/dev/null
find wiki/code -name '*.md' ! -name '_index.md' 2>/dev/null | wc -l

Then apply the generation rules from the template verbatim: group in the fixed order, drop _index, sort kebab-lexical, omit empty groups, truncate any group over 30 slugs, append the code-graph pointer only when code pages exist. Edit only the bytes between the two markers — and when an unbalanced marker is present, pair the closing marker with the last opening marker before it, never an orphan further up. If the markers are absent, append the whole ## Memory section (prose included) to AGENTS.md, creating the file if it does not exist. Never write the block into CLAUDE.md.

Report the outcome in the Phase 3 quality report as present / inserted / regenerated, and note which path (runtime or fallback) produced it.

Size guard. The block counts toward the root AGENTS.md 150-line budget (Phase 4b, check 5). Truncation keeps it near ten lines; if the file is over 150 lines, trim elsewhere — never by hand-editing inside the markers, which the next regeneration overwrites.

Phase 2: Quality Assessment

For each guidance file, evaluate against quality criteria. See references/quality-criteria.md for detailed rubrics.

Quick Assessment Checklist:

Quality Scores:

• A (90-100): Comprehensive, current, actionable
• B (70-89): Good coverage, minor gaps
• C (50-69): Basic info, missing key sections
• D (30-49): Sparse or outdated
• F (0-29): Missing or severely outdated

Phase 3: Quality Report Output

ALWAYS output the quality report BEFORE making any updates.

Format:

## Guidance File Quality Report

### Summary
- Files found: X
- Average score: X/100
- Files needing update: X

### File-by-File Assessment

#### 1. ./AGENTS.md (Project Root)
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]

#### 2. ./packages/api/CLAUDE.md (Package-specific)
...

Phase 4: Targeted Updates (Additions)

After outputting the quality report, make targeted additions only when they are clearly supported by the audit. Leave ambiguous additions as recommendations.

All additions go to AGENTS.md. Never write content to CLAUDE.md — it is an import shim (@AGENTS.md only). If Claude-specific content is needed, use .claude/rules/ (team-shared, path-scoped) or .claude.local.md (personal).

Update Guidelines (Critical):

1. Propose targeted additions only - Focus on genuinely useful info:

   • Commands or workflows discovered during analysis
   • Gotchas or non-obvious patterns found in code
   • Package relationships that weren't clear
   • Testing approaches that work
   • Configuration quirks

2. Keep it minimal - Avoid:

   • Restating what's obvious from the code
   • Generic best practices already covered
   • One-off fixes unlikely to recur
   • Verbose explanations when a one-liner suffices

3. Show diffs - For each change, show:

   • Which guidance file to update
   • The specific addition (as a diff or quoted block)
   • Brief explanation of why this helps future agent sessions

Diff Format:

### Update: ./AGENTS.md

**Why:** Build command was missing, causing confusion about how to run the project.

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev  # Start development server on port 3000
+ ```

### Phase 4b: Prune (Removals)

The audit is two-directional: add what's missing, remove what's stale. After proposing additions, scan the guidance file for content that should be removed or consolidated. See [references/update-guidelines.md](references/update-guidelines.md) "What to Remove" for the full criteria.

**Prune checks:**

1. **Validate commands.** For each documented command, check it still works:
   - `which <tool>` for CLI tools
   - `grep` in `package.json` scripts, `Makefile`, or equivalent
   - Check referenced file paths exist (`ls <path>`)
   - Flag any command that would fail

2. **Flag stale gotchas.** One-off fixes unlikely to recur, workarounds for issues long since fixed in code, env vars no longer referenced in config.

3. **Deduplicate.** Overlapping entries saying the same thing in different sections. Keep the better one, propose removing the other.

4. **Propose consolidation.** When sections grew organically and overlap, propose a merged version. Show the before/after.

5. **Size guard.** If a root `AGENTS.md` is over 150 lines (or a package-level one over 50), flag it. Suggest what to trim or move to the wiki / `references/` docs. Count the whole file, memory-map region included; trim prose and stale sections rather than the generated region, which is already bounded by its truncation rule and is restored on the next regeneration anyway.

6. **Collapse drifted CLAUDE.md.** If Phase 1b found CLAUDE.md with content beyond `@AGENTS.md`, and the extra content has been moved (to AGENTS.md, `.claude/rules/`, or `.claude.local.md`), propose collapsing CLAUDE.md back to `@AGENTS.md` only.

**Prune diff format:**

```markdown
### Prune: ./AGENTS.md

**Why:** `grunt serve` command no longer exists — project migrated to Vite.

```diff
- `grunt serve` - Start development server

Prune: ./AGENTS.md

Why: Gotcha for SSL issue was fixed in v2.1.0; no longer relevant.

- - SSL certificate errors on dev: set `NODE_TLS_REJECT_UNAUTHORIZED=0` (fixed in v2.1.0)

Apply stale or duplicate pruning directly after showing the prune diff in the quality report. Removed content is noted in the report.

### Phase 5: Apply Updates

Apply changes using the Edit tool. Preserve existing content structure.

## Templates

See [references/templates.md](references/templates.md) for guidance file templates by project type.

## Common Issues to Flag

1. **Stale commands**: Build commands that no longer work → Phase 4b prune
2. **Missing dependencies**: Required tools not mentioned → Phase 4 addition
3. **Outdated architecture**: File structure that's changed → Phase 4b prune + Phase 4 addition
4. **Missing environment setup**: Required env vars or config → Phase 4 addition
5. **Broken test commands**: Test scripts that have changed → Phase 4b prune
6. **Undocumented gotchas**: Non-obvious patterns not captured → Phase 4 addition
7. **Duplicated info**: Same content in two places → Phase 4b deduplicate
8. **Overgrown file**: AGENTS.md over 150 lines → Phase 4b size guard
9. **Missing or stale memory map**: a `wiki/` exists but AGENTS.md has no `loam:memory-map` region, or its slugs no longer match `wiki/` → Phase 1d ensure/regenerate

## User Tips to Share

When presenting recommendations, remind users:

- **Keep it concise**: Guidance files should be human-readable; dense is better than verbose
- **Actionable commands**: All documented commands should be copy-paste ready
- **Use `.claude.local.md`**: For personal preferences not shared with team (add to `.gitignore`)
- **Prefer `AGENTS.md`**: Use it for shared, harness-agnostic guidance when the repo does not already center on `CLAUDE.md`

## What Makes a Great Guidance File

**Key principles:**
- Concise and human-readable
- Actionable commands that can be copy-pasted
- Project-specific patterns, not generic advice
- Non-obvious gotchas and warnings

**Recommended sections** (use only what's relevant):
- Commands (build, test, dev, lint)
- Architecture (directory structure)
- Key Files (entry points, config)
- Code Style (project conventions)
- Environment (required vars, setup)
- Testing (commands, patterns)
- Gotchas (quirks, common mistakes)
- Workflow (when to do what)