Menu
Use when an agent is unfamiliar with a Gormes code area, a change crosses package boundaries, or a refactor needs a source-backed module map before edits.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Implement one selected repo-scoped Gormes row with tests. Use when next-work says decision=build. Do not use for decision=plan, broad parity audits, or untracked feature ideas.
Shape source-backed Gormes progress rows. Use for decision=plan builder handoffs, row splitting, feature maps, or parity planning. Do not use when decision=build or for runtime code.
Route Gormes work to the smallest repo-local skill chain. Use before substantial planning/building/refactor work, when unsure which Gormes skill applies, or when creating/improving repo-local skills.
Build one selected Gormes behavior with red-green-refactor. Use when the row or reproduced bug defines a test target. Do not use after decision=plan or for broad planning.
Move one bounded cmd/gormes command domain out of root files toward root main.go only. Use when thinning cmd/gormes, burning down loose root files, preserving CLI behavior, or catching refactor regressions during cmd moves.
Plan or implement browser automation parity. Use for Browser Use, go-browser-harness, CDP, /browser connect, browser providers, tool descriptors, and browser interaction skills.
| name | gormes-architecture-zoomout |
| description | Use when an agent is unfamiliar with a Gormes code area, a change crosses package boundaries, or a refactor needs a source-backed module map before edits. |
Use this before changing an unfamiliar subsystem, when a planned change spans packages and callers, or when the user asks to improve codebase architecture.
Inspired by mattpocock/skills zoom-out and improve-codebase-architecture; adapted for Gormes source evidence, progress rows, branch rules, and Hermes/Honcho parity boundaries.
Pick one mode before exploring:
Default to zoom-out map for vague debugging. Use architecture review when the user says “improve codebase architecture,” “find refactors,” “make this more testable,” “reduce coupling,” or “AI-navigable.”
Protect the worktree first. Run git status --short --branch --untracked-files=all. If unrelated dirty work exists, name it in the report, avoid broad formatters/regenerators, and stage only explicit architecture-skill files.
Read local maps first. Start with the current repository root's codemap.md (git rev-parse --show-toplevel); read folder codemap.md when present.
Choose one subsystem. Do not review the whole repository at once. Good first cuts are cmd/gormes setup/CLI, internal/tools, internal/gateway, internal/channels/<name>, internal/goncho, internal/memory, internal/tui, or internal/provider.
Run targeted discovery. Use commands like these, scoped to the subsystem:
find <area> -maxdepth 2 -type f -name '*.go' | sort
rg -n "type .*interface|func New|func \(.*\)|TODO|panic\(|os\.Getenv|http\.Client|time\.Now|json\.Marshal|AtomicReplace|Status|Evidence" <area>
rg -n "<public command/tool/error/status text>" cmd internal webpages/docs/content/building-gormes
go test ./<package> -run '<focused existing test pattern>' -count=1
Map the subsystem. List modules, owners, entry points, data flow, persistence, and test surfaces.
Find user-visible contracts. CLI flags, TUI text, gateway protocol, files on disk, progress rows, and Hermes parity refs.
Evaluate module depth. Use these terms consistently:
Classify architecture smells. Prefer candidates that match one or more of these Gormes-specific smells:
Apply architecture tests. For each candidate:
Score candidates. Use the scorecard below; discard candidates below 3 unless the user specifically asks to see speculative ideas.
List anti-candidates. Name tempting refactors you rejected and why, so future agents do not re-suggest them.
Separate facts from guesses. Every claim gets a file path, function, test, progress row, or command.
Run the architecture stop/ask gates. If any gate below trips, stop the review at a recommendation instead of implementation.
Recommend the smallest next skill. Usually gormes-tdd-slice, gormes-interface-designer, gormes-service-layer-refactor, or gormes-progress-slicer.
Stop and ask Juan, or route to planner, when:
Continue without asking when:
Score each candidate 0-10:
| Points | Signal |
|---|---|
| +2 | Repeated mechanics exist in two or more callers |
| +2 | Public behavior can be characterized through one seam |
| +1 | Deletion test says complexity would spread across callers |
| +1 | Refactor reduces caller knowledge/config/error handling |
| +1 | Existing tests or fixtures can protect behavior |
| +1 | Change preserves Hermes/Honcho/Gormes user-visible contracts |
| +1 | Candidate removes or centralizes one Gormes-specific smell from the taxonomy |
| +1 | First slice can update one package or one caller family without broad churn |
| -2 | Needs public behavior change without a progress row |
| -2 | Only one adapter/caller and no near-term second adapter |
| -2 | Mainly renames/moves code without improving locality |
| -2 | Requires broad edits across unrelated subsystems |
Recommendation strength:
Strong: 7-10 and first slice is clear.Worth exploring: 3-6 or needs interface design first.Speculative: 0-2; usually report as anti-candidate, not a task.Use these examples to keep reviews consistent:
| Example | Likely score | Why |
|---|---|---|
| Three channel runtimes independently redact the same token/error/status shape | 8-10 | repeated mechanics, clear caller burden, public behavior can be characterized with transcript fixtures |
cmd/gormes setup and internal/tui/admin both clamp terminal layout with copied width/height math | 6-8 | repeated mechanics and focused TUI tests, but user-visible layout must be preserved exactly |
| A package exports an interface with one implementation and tests use it only to mock private helpers | 1-3 | likely one-off seam; prefer package-local helper or deletion unless a second adapter is imminent |
| Moving files into a new package because the old package is large | 0-2 | layout aesthetics only unless caller knowledge, tests, or locality improve |
| Replacing provider-specific behavior with one generic provider abstraction | 2-5 | may reduce duplication, but high parity drift risk; route through provider parity/interface design first |
Prefer candidates with A or B evidence. Mark C as speculative unless the user asks for exploration.
Area: <subsystem>
Entry points: <files/functions>
Data flow: <source -> transform -> sink>
User-visible contracts: <CLI/TUI/API/files>
Tests/evidence: <commands/files>
Risks: <seam/persistence/security/parity>
Architecture candidates:
1. <candidate title> — <Strong/Worth exploring/Speculative> (<score>/10)
files: <paths>
current shape: <modules/callers>
interface burden: <facts callers/tests must know today>
evidence_quality: <A executable/B source/C impression>
friction: <why locality/leverage/testability is weak>
deepening move: <smaller interface or better seam>
deletion test: <complexity vanishes/spreads>
two-adapter test: <real seam/hypothetical seam>
characterization test: <focused test to write before refactor>
first safe slice: <TDD/refactor/planner action>
validation: <focused command + full gate if implemented>
Anti-candidates:
- <tempting refactor rejected> — <why>
Top recommendation: <one candidate + why>
Next skill packet:
selected_skill: <skill>
intent: <implementation/design/planning>
scope: <files/packages>
behavior_to_preserve: <contract>
first_test: <command/test name>
stop_if: <risk or blocker>
validation_matrix_row: <row from table above>
For broad architecture review requests, produce 2-4 candidates, not a grand rewrite plan. Keep the report text-first for Juan. Do not write HTML reports inside this repo; if a visual report is useful, put it under /tmp and report the absolute path.
Match the proposed next slice to the smallest proof:
| Next slice type | Minimum proof before implementation | Green gate after implementation |
|---|---|---|
| Package-local helper extraction | Characterization test through existing public caller | focused package test + git diff --check |
| New seam or adapter | Interface test with fake and production adapter evidence | focused package test + affected caller test |
| Progress-row refactor plan | go run ./cmd/progress validate before and after row edit | go test ./internal/planning/progress ./webpages/docs -count=1 |
| CLI/tool behavior-preserving refactor | CLI/tool golden or fixture test before moving code | focused command/tool test + full Go gate when feasible |
| Channel/gateway refactor | transcript/status fixture proving no duplicate/leaked output | channel/gateway focused test + progress validate |
| Persistence/config refactor | temp-home/temp-db fixture proving ordering, redaction, and atomicity | package test plus migration/config focused tests |
If no minimum proof exists, the first safe slice is to add the characterization test, not to refactor.
Use this compact packet when handing off implementation:
architecture_review_packet:
area: <subsystem>
candidate: <title>
score: <n>/10
smell: <taxonomy item>
evidence_quality: <A/B/C>
preserve_contracts:
- <CLI/tool/API/status behavior>
characterization_test:
name: <test to add or existing test to extend>
command: <focused go test command>
allowed_write_scope:
- <package/file family>
forbidden_scope:
- <public behavior or package not to touch>
next_skill: <gormes-service-layer-refactor|gormes-interface-designer|gormes-tdd-slice|gormes-progress-slicer>
If the packet cannot name a characterization test and allowed write scope, the candidate is not ready for implementation. If evidence quality is C, the next skill must be gormes-architecture-zoomout or gormes-interface-designer, not implementation.
gormes-progress-slicer or gormes-planner.