g-eskayo/marvin/architecture-review

Architecture Review

Architectural review of the whole agent system. Generate suggestions → queue in priority order → wait for authorization → implement.

Never implement without explicit approval.

Scope

Whole system, expanded 2026-07-09 (was previously a named subset — CLAUDE.md, lexicon, skills, commands, one script — scope had drifted narrower than the skill's own stated purpose). Review everything under:

• ~/.agents/ — every skill's SKILL.md and its scripts, every lib/ utility, every ADR/CONTEXT.md, bench/, brain-map/ — not just a hand-picked subset
• ~/.claude/ — CLAUDE.md, lexicon.md, commands/, handoffs/, suggestions.md itself, launchd job configs, hook wiring in settings.local.json
• Cross-machine infra (marvin-network.json, task_dispatch.py, cross_machine_merge.py) where it affects reliability or organization, same as anything else

Still bounded by the review process below (token reduction, retrieval speed, organization, pipeline logic, reliability, robustness) — "whole system" means no arbitrary exclusion list, not "review everything exhaustively every single pass."

Review Process

1. Audit the system

Read each component. For each, ask:

• Tokens: is this longer than it needs to be? Redundant with another file?
• Speed: would reorganizing make retrieval/matching faster?
• Reliability: any single points of failure? Scripts that could break silently?
• Organization: does the file structure reflect how things are actually used?
• Robustness: what happens when something is missing or malformed?
• Maintenance burden (added 2026-07-09, Gil's direction): does two-or-more scripts implement the same shape of logic on different data (not necessarily copy-pasted — a duplicated pattern counts)? Every new script is something to maintain going forward; growing that count without checking for reuse first is itself a cost. Flag genuine duplication; don't force consolidation for its own sake at 2 call sites (see the priority_rank.py entry in suggestions.md for the calibration — noted, not force-extracted).

2. Generate suggestions

For each finding that passes the bar (see below), write a suggestion entry with an explicit priority — this file is a priority-ordered, reorderable backlog (added 2026-07-09), not a chronological log. Score priority using the same compounding-leverage lens as everywhere else in this system (~/.claude/marvin-roadmap.md's north-star section): does this unlock or cheapen multiple future items, not just its own standalone value.

Entry format:

## [Title]
**Priority**: [1-10, 10 = highest — see scoring guidance below]
**Status**: pending
**Impact**: [token-reduction | speed | reliability | organization | robustness]
**Effort**: [low | medium | high]
**Why**: [one line — the problem]
**What**: [exact change]
**How**:
- step 1
- step 2
**Added**: [YYYY-MM-DD]

Priority scoring: weight compounding leverage above standalone impact — an item that makes several future items cheaper/faster/possible outranks a bigger one-off win. Within that, break ties by Impact (token-reduction/speed rank above organization/robustness per ## Optimization Priorities below) then Effort (lower effort wins at equal impact).

After writing the entry, run the sorter so the file actually reflects current priority order, not insertion order:

~/.agents/venv/bin/python ~/.agents/skills/architecture-review/scripts/sort_suggestions.py

3. Present to user

After writing to the queue, surface new suggestions:

[N] new optimization suggestion(s) queued.

Run /architecture-review review to see them, or I'll show them now.

Don't dump the full list unprompted — respect caveman mode.

4. On approval

When user approves a suggestion (by name or number):

1. Read the suggestion's How steps
2. Implement exactly as specified
3. Update status to done in ~/.claude/suggestions.md
4. Confirm what changed

On rejection: update status to rejected. Don't re-raise.

Suggestion Bar

Only queue suggestions that pass all three:

• Concrete: exact file + change specified, not vague ("improve clarity")
• Measurable: tokens saved, files reduced, steps eliminated — quantify if possible
• Net positive: improvement outweighs risk of breaking something

Do not queue:

• Stylistic preferences with no functional impact
• Changes that increase complexity for marginal gain
• Anything that would alter behavior in non-obvious ways without flagging it clearly

Review Subcommand

When invoked as /architecture-review review:

• Read ~/.claude/suggestions.md — already in priority order (highest first), since the file is kept sorted
• Show all pending items in compact form, in that order
• Ask: "Approve any? (by title or 'all')" — also accept reprioritization requests ("bump X", "this is more important than Y"): update the entry's Priority field and re-run sort_suggestions.py

Optimization Priorities

Ranked by value:

1. Token reduction — shorter SKILL.md files, compressed routing descriptions, deduplicated instructions
2. Retrieval speed — routing table accuracy (fewer false positives), skill descriptions that match faster
3. Organization — related skills grouped, dead files removed, naming consistent
4. Pipeline logic — background_review.py robustness, handoff flow, session-start checks
5. Reliability — hardcoded/stale counts, scripts referenced but not present, scripts that fail silently
6. Robustness — graceful degradation when files missing, fallback behavior documented