| name | clark-survey |
| description | Autonomous codebase health scan for vocabulary drift, naming convention violations, structural anti-patterns, documentation staleness, and test health. Produces prioritized findings as Linear issues. Use for health checks, scheduled scans, or after heavy unreviewed agent work. |
| context | fork |
| agent | clark |
Clark: Survey
Autonomous scan. Broad, pattern-oriented. Not reviewing any single PR or milestone, but looking across the codebase for accumulating drift, emerging patterns, and opportunities to tighten.
Designed to run on a schedule (nightly, weekly) or on-demand when a general health check is needed. Produces actionable findings as Linear issues.
What to Scan
1. Vocabulary Drift
Search the codebase for terms that do not belong. Same vocabulary check as calibrate, but applied to the entire codebase rather than a specific changeset.
rg -i "handler|middleware|endpoint|controller" --type ts -g '!node_modules'
rg -i "registry|collection|manifest" --type ts -g '!node_modules' -g '!package.json'
rg -i '"serve"|"mount"|"wire"' --type ts -g '!node_modules'
Not every match is a violation. Context matters. But every match is worth examining.
2. Naming Convention Drift
Look at recent exports and public API additions. Do they follow ADR-0001?
rg "^export " --type ts -g '!node_modules' -g '!*.test.*' -g '!*.spec.*'
Check for: factories without create*, derivations without derive*, test helpers without test*, validators without validate*.
3. Structural Patterns
Look for code smells that indicate architectural drift:
- Surface types in implementations: imports of
Request, Response, McpSession in trail files
- Direct throws:
throw statements in implementation code (should be Result.err())
- Console usage:
console.log, console.error in non-surface code
- Direct
.run() calls: should be ctx.compose()
rg "throw " --type ts -g '*/trails/*' -g '!*.test.*'
rg "console\." --type ts -g '!node_modules' -g '!*.test.*'
rg "\.run\(" --type ts -g '*/trails/*'
4. Documentation Staleness
Compare the docs against the code:
- Do the ADRs reflect the current state? Check status fields.
- Does
lexicon.md cover all exported terms?
- Does
architecture.md match the actual package structure?
- Is
horizons.md current? Have any horizon items shipped without being moved to "shipped"?
5. Test Health
- Does
bun run test pass cleanly?
- Are there trails without examples?
- Are there examples that are stale (would fail if re-evaluated)?
- Does
trails warden report violations?
bun run test
bun run typecheck
trails warden
trails survey brief
6. Growth Without Governance
Look for quantitative signals:
- Packages or directories that have grown significantly without corresponding ADRs
- New error classes that do not fit the taxonomy
- New trail IDs that do not follow naming conventions
- New dependencies added without clear justification
Output
## Survey: [date]
### Critical (file immediately)
- [finding]: [specific files/lines, what is wrong, recommended fix]
### Important (file this week)
- [finding]: [description, impact, recommendation]
### Minor (file for backlog)
- [finding]: [description, low urgency but worth tracking]
### Healthy
- [areas that look good, briefly]
### Trends
- [patterns across multiple findings]
- [things getting better or worse over time]
Linear Issue Format
For each finding that warrants an issue:
**Title:** [Clark: brief description]
**Labels:** clark-survey, [area: vocabulary | architecture | naming | testing | docs]
**Priority:** [urgent | high | medium | low]
**Description:**
[What was found]
[Where it was found (files, lines)]
[Why it matters (which principle/convention)]
[Recommended fix]
State Between Runs
If a previous survey exists at .trails/clark/survey-latest.md, read it before running. Note:
- Findings that were filed and resolved (mark as cleared)
- Findings that were filed but not resolved (note persistence)
- Findings that are new since last survey
- Trends over time
After the survey, write the current findings to .trails/clark/survey-latest.md so the next run has context.
Reference
docs/lexicon.md — lexicon to enforcedocs/adr/001-naming-conventions.md — naming conventions to checkdocs/architecture.md — structural expectationsAGENTS.md — current conventions.trails/clark/survey-latest.md — previous survey results (if exists)
