---
name: Legibility Check
slug: legibility-check
category: Quality
description: Legibility Check runs deterministic checks on maintainer docs to catch stale standards metadata, broken architecture manifest paths, and plan state drift before CI does. Use it after modifying files under .agents/docs/standards/, .agents/docs/plans/, .agents/docs/architecture/, or AGENTS.md.
github: "https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/legibility-check"
language: Python
stars: 3064
forks: 266
install: "npx degit https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/legibility-check ~/.claude/skills/legibility-check"
installs_to: ~/.claude/skills/legibility-check
source_path: .agents/skills/legibility-check/SKILL.md
collection_size: 11
category_size: 1354
collection_url: "https://dirskills.com/collections/liaohch3/claude-tap"
added: 2026-08-17T07:09:16.174Z
last_synced: 2026-08-17T07:09:16.174Z
canonical_url: "https://dirskills.com/skills/legibility-check"
---

# Legibility Check

Legibility Check runs deterministic checks on maintainer docs to catch stale standards metadata, broken architecture manifest paths, and plan state drift before CI does. Use it after modifying files under .agents/docs/standards/, .agents/docs/plans/, .agents/docs/architecture/, or AGENTS.md.

**Install:**

```bash
npx degit https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/legibility-check ~/.claude/skills/legibility-check
```

## README

# Legibility Check

Run deterministic checks for maintainer docs that mirror what CI enforces via `.github/workflows/legibility.yml`. Catching these locally saves a round-trip to CI.

## What it checks

1. **Standards freshness** — every `.agents/docs/standards/*.md` must have frontmatter with `owner`, `last_reviewed` (ISO date), and `source_of_truth`. Files reviewed more than 60 days ago produce a warning.
2. **Architecture manifest** — every path listed in `.agents/docs/architecture/manifest.yaml` under `expected_paths:` must exist in the repo.
3. **Plan state drift** — every `.agents/docs/plans/**/*.md` must have a `status` frontmatter field (`active`, `completed`, or `cancelled`). Completed plans must not contain unchecked `- [ ]` checkboxes (outside fenced code blocks).

## Run

```bash
uv run python scripts/check_legibility.py
```

Options:
- `--freshness-days N` — change the staleness threshold (default: 60)
- `--strict-freshness` — promote stale warnings to failures
- `--repo-root PATH` — override repo root (default: cwd)

## Fixing common failures

| Failure | Fix |
|---------|-----|
| `missing frontmatter key 'X'` | Add the missing key to the YAML frontmatter block at the top of the file |
| `last_reviewed must be ISO date` | Use `YYYY-MM-DD` format |
| `last_reviewed ... is stale` | Update `last_reviewed` to today's date after reviewing the content |
| `expected path missing: X` | Either create the file or remove the stale entry from `manifest.yaml` |
| `status must be one of [...]` | Add `status: active` (or `completed`/`cancelled`) to plan frontmatter |
| `completed plan still contains unchecked TODO` | Check off remaining items or change status back to `active` |

## After fixing

Re-run the check to confirm all issues are resolved before committing:

```bash
uv run python scripts/check_legibility.py && echo "All clear"
```