senior-survey
Skill0 starsChanged 58 days agoApache-2.0View on GitHub
Use BEFORE creating any new file under src/. Guides grep + classify + decide protocol and emits a structured Survey block for the plan that the pre-edit hook can validate.
In this repository23 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- architect-reviewSkill
- brainstormingSkill
- clean-codeSkill
- close-gold-gapSkill
- codebase-auditSkill
- configureSkill
- context-rot-managementSkill
- epic-decomposeSkill
- gold-auditSkill
- impactSkill
- levelupSkill
- product-acceptanceSkill
- refutationSkill
- ssot-navigationSkill
- tabletopSkill
- tddSkill
- understand-codeSkill
- verificationSkill
- visual-verificationSkill
- wave-drainSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Use this skill before writing any new file under src/.
- Very specific: line 92
If validation fails: STOP — CANON-16 violation.
- Very specific: line 98
If your task creates multiple new src/ files, add one ## Existing Code Survey block per file.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Senior Code Survey
Use this skill before writing any new file under src/. It ensures you reason like a senior engineer: identify what already exists, decide the minimum viable path, and document the decision with evidence.
When to Use
Any time you are about to call Write with a path under src/ that does not yet exist.
Skip When
- File already exists (you are editing, not creating)
- Target is under
__tests__/,docs/,scripts/— not undersrc/ - Target is a test file (
*.test.ts,*.spec.ts)
Protocol
Step 1 — Name the target
State:
- Relative path:
src/<path/to/file>.ts - Main export(s) you plan to add
Step 2 — Run ≥3 searches
Execute these (replace <Name> and <keyword> with your specific terms):
grep -r "export.*<Name>" src/ --include="*.ts" -l
grep -r "<keyword>" src/ --include="*.ts" -l
ls src/<sibling-directory>/Capture the results (file:line hits or (no match)).
Step 3 — Classify
Choose one decision keyword:
| Keyword | Meaning |
refactor-applied | Similar code found; you are extending/extracting instead of creating new |
refactor-rejected | Similar code found but refactoring would pollute the abstraction |
extend | Adding to an existing file/module rather than creating new |
extract | Pulling shared logic out of existing files into a new shared utility |
new file justified | No similar code; new responsibility is architecturally distinct |
no-similar-code | Grepped thoroughly; nothing similar exists |
Step 4 — Emit the Survey block
Paste this into your plan (one block per new file):
## Existing Code Survey
- **Target:** `src/<relative/path>.ts`
- **Decision:** `<keyword from table above>`
### Evidence
- `grep "export.*<Name>" src/ --include="*.ts" -l` → `<file:line>` | `(no match)`
- `grep "<keyword>" src/ --include="*.ts" -l` → `<file:line>` | `(no match)`
- `ls src/<sibling>/` → `<entries>` | `(none similar)`
### Rationale
<2–4 sentences. State: what similar code you found (or didn't find); why refactoring was or was not viable; what new responsibility makes this file architecturally justified. Must be ≥200 non-whitespace characters — a stub like "needed" will be rejected by the hook.>Hook Validation
The pre-edit-plan-anchor.mjs hook validates this block before allowing the Write. It requires:
- **Target:** \src/your/file.ts`` — exact relpath of the file being written- **Decision:** \<keyword>`` — one of the six valid keywords### Evidencesubsection with ≥3 lines starting with- `grepor- `ls### Rationalesubsection with ≥200 non-whitespace characters
If validation fails: STOP — CANON-16 violation. Fix the Survey — the hook is telling you
the plan lacks the evidence a reviewer needs, and the fix is always to supply it, not to
route around the hook.
Multi-File Tasks
If your task creates multiple new src/ files, add one ## Existing Code Survey block per file. Each block must have its own Target line matching that specific file.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

