improve-codebase-architecture-project

This skill runs unattended in CI. It picks one architectural improvement, publishes it as a PRD, and emits a structured <output> block for the driver script. No grilling, no HTML, no human in the loop.

Methodology

You are looking for deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Glossary — use these terms exactly in the PRD

• Module — anything with an interface and an implementation (function, class, package, slice).
• Interface — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type 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.
• 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

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

Use CONTEXT.md vocabulary for domain language. Do not re-litigate decisions recorded under docs/adr/.

Process

1. Read prior proposals

gh issue list --label "source:architecture-review" --state all --limit 200 \
  --json number,title,body,state,labels

Read every result. Build a mental list of: which modules each prior PRD touches, what friction it addresses, and whether it was merged, closed-without-merge, or still open. All of these count as "already proposed" — the goal is novelty, not re-litigation.

If a prior proposal was closed-without-merge with a comment giving a load-bearing reason, treat that reason as binding: do not re-propose anything matching that reasoning.

2. Explore the codebase

Read CONTEXT.md and any relevant ADRs under docs/adr/ first.

Then use the Agent tool with subagent_type=Explore to walk the repo. Note friction organically:

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

3. Filter against prior proposals — loose-duplicate rule

A candidate is a duplicate if either:

• it touches substantially the same modules as a prior proposal, or
• it addresses the same underlying friction, even with a different angle.

When in doubt, treat it as a duplicate. The goal is one fresh proposal per run — duplicates spam the backlog.

4. Pick the single top candidate

Internally generate 3-5 candidates, rank them, pick one. Rank on:

• Leverage — how much downstream code benefits
• Locality gain — how much complexity gets concentrated
• Test surface improvement — does the deepened interface make tests cleaner?
• Cost-to-value — small refactors that unlock a lot beat sprawling rewrites

If every reasonable candidate is a duplicate, skip (see step 6).

5. Format the PRD using /to-prd-project — but do NOT publish

Follow the /to-prd-project skill to produce the PRD content: same template (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes) and same writing discipline.

Critical override: do not run gh issue create. The workflow publishes the issue itself so that creation and labelling are atomic. Your job is to write the title and body; the workflow handles the GitHub mutation.

In addition to the standard PRD-template sections, the body must include an Architecture review section at the top with:

• Files — which modules are involved
• Problem — the friction in current architecture, in CONTEXT.md + glossary vocabulary above
• Solution — what changes, in plain English
• Benefits — framed in terms of locality and leverage; how tests improve
• Before / After diagram — a fenced mermaid block showing the shallow → deep transition. GitHub renders Mermaid natively in issue bodies.
• Recommendation strength — Strong, Worth exploring, or Speculative

6. Emit structured output

The driver script parses a single <output> block at the end of your response.

On success (a fresh proposal was found):

<output>
{
  "status": "proposed",
  "title": "<the PRD title — short, imperative, < 80 chars>",
  "body": "<the full PRD markdown body, including the Architecture review section and all standard PRD-template sections>",
  "oneLineSummary": "<one sentence describing the proposal, for the workflow run summary>",
  "candidatesConsidered": [
    "<one-line description of candidate 1>",
    "<one-line description of candidate 2>",
    "<one-line description of candidate 3>"
  ]
}
</output>

The workflow takes title + body and runs gh issue create --label "source:architecture-review". Do not call gh issue create yourself.

If every reasonable candidate was already proposed:

<output>
{
  "status": "skipped",
  "reason": "<one or two sentences naming the candidates considered and which prior issues blocked them>"
}
</output>

Rules

• Read-only everywhere. No commits, no edits to CONTEXT.md / ADRs / source files, no gh issue create, no gh issue edit. The workflow does the publish. If you spot a stale doc, mention it inside the PRD body — don't edit it.
• One proposal per run. Never publish more than one PRD in a single invocation.
• No grilling, no questions. There is no user. Make the call and emit the <output> block.