deft-directive-gh-arch · git:20260701.0a1aa9c · 2026-07-01 · sha256 ead1b1fa03aed9fd

deft-directive-gh-arch git:20260701.0a1aa9cA

Immutable. This exact content never changes and is served at /api/v1/blob/ead1b1fa03aed9fd.

---
name: deft-directive-gh-arch
description: >-
Explore a codebase for architectural improvement opportunities -- deepen
shallow modules, generate competing interface designs in parallel via sub-
agents, and file a refactor RFC as a GitHub Issue. Use when improving
architecture, finding refactoring opportunities, or making a codebase more
testable and AI-navigable. Requires the GitHub CLI (gh).
---

# Deft GH Arch

Explore a codebase for architectural friction, surface opportunities to deepen shallow modules, generate competing interface designs in parallel, and file a refactor RFC as a GitHub Issue.

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

> Inspired by [improve-codebase-architecture](https://github.com/mattpocock/skills/tree/main/improve-codebase-architecture) from [mattpocock/skills](https://github.com/mattpocock/skills). Adapted to deft's domain model conventions and GitHub CLI workflow.

## When to Use

- Codebase has grown and modules feel tightly coupled or hard to test
- New feature work keeps touching the same files unexpectedly
- User says "improve the architecture" or "this is hard to test"
- Pre-implementation cleanup before a major new feature

## Prerequisites

- ! Verify `gh` is authenticated: `gh auth status` — stop and report if not

---

## Core Concept: Deep Modules

A **deep module** (John Ousterhout, *A Philosophy of Software Design*) has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside.

Shallow modules are the inverse: their interface is nearly as complex as the implementation. They force callers to know too much.

---

## Process

### Step 1: Explore the codebase

Navigate the codebase naturally. Note where you experience friction — **the friction IS the signal**:

- ~ Where does understanding one concept require bouncing between many small files?
- ~ Where are modules so shallow that the interface is nearly as complex as the implementation?
- ~ Where have pure functions been extracted just for testability, but real bugs hide in how they're called?
- ~ Where do tightly-coupled modules create risk at integration seams?
- ~ Which parts are untested, or hard to test?

- ! If `core/glossary.md` or `UBIQUITOUS_LANGUAGE.md` exists, read it — domain term precision matters when naming interfaces
- ⊗ Follow rigid heuristics — explore organically

### Step 2: Present candidates

Present a numbered list of deepening opportunities. For each:

- **Cluster** — which modules/concepts are involved
- **Why they're coupled** — shared types, call patterns, co-ownership of a concept
- **Test impact** — what existing tests would be replaced by clean boundary tests

⊗ Propose interfaces at this step — present candidates only.

! Ask: "Which of these would you like to explore?"

### Step 3: Frame the problem space

Before spawning sub-agents, write a brief user-facing explanation:
- The constraints any new interface must satisfy
- The dependencies it must manage
- A rough illustrative sketch to make constraints concrete (not a proposal)

Show this to the user, then immediately proceed to Step 4. The user reads while sub-agents work.

### Step 4: Design multiple interfaces in parallel

Spawn 3+ sub-agents with **radically different** design constraints. Each produces:

1. Interface signature (types, methods, params)
2. Usage example showing how callers use it
3. What complexity it hides internally
4. How dependencies are handled
5. Trade-offs

**Agent constraints:**
- Agent 1: "Minimize the interface — aim for 1–3 entry points max"
- Agent 2: "Maximize flexibility — support many use cases and extension points"
- Agent 3: "Optimize for the most common caller — make the default case trivial"
- Agent 4 (if applicable): "Design around ports & adapters for cross-boundary dependencies"

- ! The sub-agent dispatch envelope MUST include `templates/agent-prompt-preamble.md` verbatim (or by reference) per AGENTS.md `## Multi-agent orchestration discipline (#954)`. The preamble carries the AGENTS.md read mandate, the #810 xBRIEF gate walkthrough, the PowerShell 5.1 non-ASCII rule, REST-over-GraphQL rules, and the mandatory DONE message protocol -- without it, the recurrence patterns documented in #954 re-fire on every fresh dispatch.

Present designs sequentially, then compare in prose. Give your own recommendation — which is strongest and why. If elements combine well, propose a hybrid. Be opinionated.

### Step 5: User picks an interface

! Wait for explicit user selection (or acceptance of your recommendation) before filing.

### Step 6: File the GitHub Issue

- ! Create a refactor RFC immediately using `gh issue create` with the template below
- ~ Issue-label hygiene: before filing, inspect the target repo's existing labels with `gh label list` or the labels API; choose one or more suitable existing labels when practical, or explicitly note that no label was applied. This is a recommendation, not a gate -- do not block issue creation solely because no label fits, and do not invent ad hoc labels outside the repo's existing label set.
- ! After creating, print the issue URL
- ! When the RFC is filed as an umbrella with companion child issues (e.g. an interface-extraction RFC plus one child per migrating caller), record the cohort in `xbrief/.eval/slices.jsonl` via `scripts/slice_record.py::write_slice(...)` with `actor="skill:gh-arch"` -- this is the durable production-side record consumed by `task triage:audit --orphans` (#1132 / D13). Same usage pattern as `skills/deft-directive-gh-slice/SKILL.md` Step 6; idempotent on retry. Skip when the RFC is a single-issue "file and forget" with no child cohort.
- ! Confirm skill exit: "deft-directive-gh-arch complete — RFC filed at <url>."
- ~ Suggest next steps: run `deft-directive-refinement` to slot the RFC into the xBRIEF lifecycle, or assign the issue for swarm pickup.

**Issue template:**

```
## Problem

Describe the coupling or shallowness found. What makes this hard to test or extend?
Describe modules and behaviors — NOT specific file paths or line numbers.

## Proposed Interface

The chosen interface design (from the parallel session).

Include:
- Interface signature (types / methods / params)
- Usage example
- What complexity it hides

## Dependency Strategy

How the new interface handles its dependencies (injection, ports & adapters, etc.)

## Test Impact

What existing tests this replaces, and what new boundary tests become possible.

## Trade-offs

What this design gains and gives up vs the current implementation.

## Acceptance Criteria

- [ ] Interface is implemented and passes all boundary tests
- [ ] Existing callers are migrated
- [ ] Old internal tests replaced by boundary tests
- [ ] task check passes
```

---

## Anti-Patterns

- ⊗ Proposing an interface before presenting candidates to the user
- ⊗ Designing only one interface — parallel designs are required to surface real trade-offs
- ⊗ Filing the issue before the user approves the chosen design
- ⊗ Including specific file paths or line numbers in the issue body (couples to current layout)
- ⊗ Proceeding without `gh` authentication
- ⊗ Dispatch sub-agents without the canonical preamble — see `templates/agent-prompt-preamble.md` and AGENTS.md `## Multi-agent orchestration discipline (#954)`.