deft-directive-gh-arch · diff

git:20260622.035cde3 to git:20260701.0a1aa9c

3 added, 3 removed. Audit A to A.

---

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 vBRIEF 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.

+ - ! 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 `vbrief/.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.

+ - ! 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 vBRIEF lifecycle, or assign the issue for swarm pickup.

+ - ~ 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)`.