improve-codebase-architecture

name	improve-codebase-architecture
description	Find deepening opportunities in the ELI PANDA codebase, informed by the domain glossary in `docs/CONTEXT.md`, the per-feature pages in `docs/technical/`, the ADRs in `docs/adr/`, and the conventions in `CLAUDE.md`. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make the codebase more testable and AI-navigable.

Improve Codebase Architecture

Surface architectural friction in this codebase and propose deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Glossary

Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in LANGUAGE.md.

• Module — anything with an interface and an implementation (a function, a hook, a .cont.tsx/.comp.tsx pair, a Zustand store, a feature folder under src/modules/, a server-side helper).
• Interface — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the TypeScript signature.
• Implementation — the code inside.
• Depth — leverage at the interface: a lot of behaviour behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation.
• Seam — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
• Adapter — a concrete thing satisfying an interface at a seam.
• Leverage — what callers get from depth.
• Locality — what maintainers get from depth: change, bugs, knowledge concentrated in one place.

Key principles (see LANGUAGE.md for the full list):

• Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
• The interface is the test surface.
• One adapter = hypothetical seam. Two adapters = real seam.

This skill is informed by PANDA's technical docs. They give names to good seams and record decisions the skill should not re-litigate.

Project context this skill relies on

• docs/CONTEXT.md — cross-cutting domain glossary. The first place to look when naming a deepened module. Authoritative names; full definitions live on the per-feature pages it links to.
• docs/technical/app-architecture.md — stack, module layout, request lifecycle, deprecated/legacy clusters, maintenance recommendations. Read this first when proposing cross-cutting refactors.
• docs/technical/<feature>.md (e.g. orders-and-order-items.md, catalogue-and-items.md, permissions-model.md, systems-family/*.md) — per-feature domain vocabulary and known integration points. Read the page covering the area you're touching before naming anything.
• docs/adr/ — architecture decision records. Check this directory for prior decisions that would conflict with a proposed refactor. See docs/adr/README.md for when an ADR should be written.
• CLAUDE.md — coding conventions, container/component split, toast/fetch/modal patterns.
• .agents/skills/architecture/SKILL.md — canonical folder layout and file-naming rules. A deepening proposal that moves code must respect these or call out the deviation explicitly.

The ADR directory is intentionally lightweight today. Decisions also live in the Maintenance recommendations, Deprecated / legacy, Open questions, and 🔮 Planned sections of the per-feature pages and app-architecture.md — treat those sections as informal ADRs and promote them into docs/adr/ when a real decision crystallizes.

Process

1. Explore

Read docs/CONTEXT.md for vocabulary, the relevant docs/technical/ page(s) for the area, and app-architecture.md for anything cross-cutting. Scan docs/adr/ for any decision that touches the area. Note the existing Maintenance recommendations and Open questions in the technical pages — your proposals should either build on them or explain why they're wrong.

Then use the Agent tool with subagent_type=Explore to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:

• Where does understanding one concept require bouncing between many small modules?
• Where are modules shallow — interface nearly as complex as the implementation?
• Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?
• Where do tightly-coupled modules leak across their seams?
• Which parts of the codebase are untested, or hard to test through their current interface?

Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.

PANDA-specific friction patterns to look for

The codebase has recurring shapes that often produce shallow modules. Use these as prompts, not as a checklist:

• .cont.tsx leaking into .comp.tsx — a "pure" component that still reads from a store, calls a mutation, or knows about GraphQL types. The container's interface is wider than it looks. Deepening usually means pulling logic back into the container (or a hook) and narrowing the props the .comp.tsx receives.
• Hooks extracted for tests, then called from one place — a useXyz hook whose body is small and whose only caller is one container. The deletion test usually clears it.
• Mutation glue around queryMutate — wrappers that re-throw, re-shape, or re-toast around an axios-shaped response. The duplication is locality begging to live behind toast.promise (see the toast skill) or a typed mutation helper.
• Filter / table state spread across module store + useTableStateStore + URL params — three places to update when a filter is added. A deeper module owns the filter state and exposes a small read/write interface.
• Modal duality — code that touches both useModalStore (legacy) and useDynamicModalStore (current). See app-architecture.md "Maintenance recommendations" #3; new proposals should pick the dynamic side.
• fetchClient / axiosInstance / queryMutate's AxiosResponse<T> shape — three transports for the REST gateway. The interface is wider than the work needs (see app-architecture.md "Maintenance recommendations" #1).
• Form module + Zod schema + RHF wiring repeated per feature — wizard steps, field-level Zod, RHF resolver bindings duplicated across src/modules/<feature>/components/. Look for a deeper "form module" the feature can instantiate.
• GraphQL query + custom hook + container plumbing — a query is defined in queries/, a typed hook generated by codegen, then re-wrapped by a feature hook that adds one parameter. Often the codegen-generated hook is already deep enough.

These are pointers, not mandates. Use the deletion test before proposing any of them.

2. Present candidates

Present a numbered list of deepening opportunities. For each candidate:

• Files — which files/modules are involved (use repo-relative paths like src/modules/orders/Orders.cont.tsx:42)
• Problem — why the current architecture is causing friction
• Solution — plain English description of what would change
• Benefits — explained in terms of locality and leverage, and also in how tests would improve

Use docs/CONTEXT.md + docs/technical/ vocabulary for the domain, and LANGUAGE.md vocabulary for the architecture. If docs/CONTEXT.md (and docs/technical/orders-and-order-items.md) calls something an "order line," say "the order-line intake module" — not "the OrderItemHandler," not "the order-item service."

Existing decision conflicts: if a candidate contradicts an ADR in docs/adr/, or an item in a docs/technical/ page's Maintenance recommendations, Open questions, or Deprecated / legacy section, mark it clearly (e.g. "contradicts ADR-0007 — but worth reopening because…" or "contradicts app-architecture.md Maintenance rec #2 — but worth reopening because…"). Don't list every theoretical refactor those sources forbid.

Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"

3. Grilling loop

Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive. The companion grill-me skill describes the cadence.

Side effects happen inline as decisions crystallize:

• Naming a deepened module after a concept that's not in docs/CONTEXT.md? Add a short entry to docs/CONTEXT.md (one or two lines + link to the per-feature page that owns the long definition). If the long definition doesn't exist yet, add it to the relevant docs/technical/ page (or app-architecture.md if it's cross-cutting). Don't invent terminology that lives only in code.
• Sharpening a fuzzy term during the conversation? Update docs/CONTEXT.md and the per-feature doc right there. Vocabulary drift across docs is the most common cause of repeat re-suggestions.
• User rejects the candidate with a load-bearing reason? Offer to record it as an ADR under docs/adr/, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Use the template at docs/adr/0000-template.md. Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. For ephemeral or open-ended rejections, an Open question entry in the per-feature docs/technical/ page is the right home instead.
• Want to explore alternative interfaces for the deepened module? See INTERFACE-DESIGN.md.
• Deepening crosses into a domain another skill already owns? Defer to it for the implementation shape: fetching for query/mutation hooks, toast for mutation feedback, modals for dialog/sheet wiring, tables for PandaTableV2, wizard for multi-step forms, architecture for where new files land. The architectural argument is still yours; the local pattern is theirs.