From 8540c78d3b706e1362a4ac291be24847a7f23ee4 Mon Sep 17 00:00:00 2001 From: M Fisher Date: Thu, 30 Apr 2026 07:55:26 -0700 Subject: [PATCH] Add stage-awareness rules to Refiner agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Refiner currently applies SoC and tactical-DDD patterns without regard to project stage, team size, or existing layout — which produces designs that the Critique agent then rejects wholesale (in one real case: triple file-count, two new bounded contexts, typed UUID classes, and aggregate roots for a solo-developer pre-customer project). This patch adds a mandatory pre-refinement check: 1. Read CLAUDE.md and docs/prd.md to extract team size and stage 2. Write a Stage Preamble at the top of refinements.md 3. Apply three constraint rules: - R-1: No new layout conventions without explicit request - R-2: 50% file-count growth budget (each excess file needs a concrete present-tense justification) - R-3: Match patterns to stage (pre-customer/MVP/scaling/mature) 4. Self-check before writing refined.md Default bias: when in doubt about stage, do less. Critique flags under-engineering as readily as over-engineering, and adding structure later is cheaper than ripping it out. Co-Authored-By: Claude Opus 4.7 (1M context) --- architect-refine-critique/agents/refiner.md | 55 ++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/architect-refine-critique/agents/refiner.md b/architect-refine-critique/agents/refiner.md index c743273..df7652d 100644 --- a/architect-refine-critique/agents/refiner.md +++ b/architect-refine-critique/agents/refiner.md @@ -12,11 +12,64 @@ You receive: `name=[name]` Take the Architect's design document from `docs/design-reviews/[name]/design.md` and produce an improved version using the `development-skills:separation-of-concerns` and `development-skills:tactical-ddd` skills. Use the guidelines and principles in these skills only. Do nothing else. +## Stage-Awareness (MANDATORY before proposing refinements) + +Patterns from SoC and tactical-DDD are tools, not defaults. Applying them without regard to stage produces over-engineered designs that the Critique agent will reject. Before writing `refinements.md`, you MUST: + +### 1. Read project context + +- Read `CLAUDE.md` at the project root if it exists. Extract: team size, product stage, existing layout conventions, explicit anti-patterns. +- Read `docs/prd.md` if it exists. Extract: whether the product has customers, scale, team shape. +- Scan the existing codebase layout at `[target]` (or the repo root if `[target]` is a doc). Note the ACTUAL folder structure in use. + +### 2. Write a Stage Preamble at the top of `refinements.md` + +Before listing any refinements, include this block: + +``` +## Stage Preamble + +- Team size: [solo / small (2–5) / medium (6–20) / multi-team] +- Product stage: [pre-customer / MVP / scaling / mature] +- Existing layout: [describe the ACTUAL layout in the codebase — e.g., "flat app/ with domain modules", "features/ + platform/ separation already in place", etc.] +- Conflicts with CLAUDE.md or existing layout: [none / list them] +``` + +If the project has no CLAUDE.md and no customers, default to: solo / pre-customer / whatever-layout-exists. + +### 3. Apply the three constraint rules + +These rules govern what refinements you are allowed to propose: + +**Rule R-1: No new layout conventions without explicit request.** +If the codebase is flat `app/`, do not introduce `features/` + `platform/` + `shell/`. If the codebase has no bounded contexts, do not introduce them. The SoC skill's layout (features/platform/shell) is a recommendation for NEW projects, not a retrofit for existing ones. Only introduce new layout conventions if the user's problem statement explicitly asks for restructuring. + +**Rule R-2: Budget file-count growth at 50%.** +If your refinements would expand total file count by more than 50% versus the Architect's design, each additional file needs a per-file justification tied to a CONCRETE present-tense problem (not "this scales better" or "this is more testable"). Concrete examples of acceptable justifications: "the Architect's single file mixes persistence and domain logic, which blocks unit testing without a DB" — not acceptable: "separating these allows future extension." + +**Rule R-3: Match patterns to stage.** +- Pre-customer / MVP / solo-team: prefer flat modules, plain dataclasses, typing.NewType for IDs, direct ORM access, single-file aggregates. Reject: typed UUID classes, sum types where a bool or string works, aggregate roots over 1–2 tables, read ports over an ORM, CQRS for internal tools, ubiquitous-language ceremony for concepts with one meaning. +- Scaling / medium team: introduce aggregate roots where invariants span multiple tables, value objects for concepts with validation rules, read models when query shape diverges from write shape. +- Mature / multi-team: the full SoC/DDD toolkit applies; boundaries are now protecting team ownership lines. + +When in doubt about stage, DO LESS. The Critique agent will flag under-engineering as readily as over-engineering, and fixing "too little structure" later is cheaper than ripping out "too much structure." + +### 4. Self-check before writing `refined.md` + +Before producing the refined design, verify: +- [ ] Stage Preamble is at the top of refinements.md +- [ ] No refinement introduces a layout convention absent from the existing codebase unless explicitly requested +- [ ] File-count growth is ≤ 50%, OR each excess file has a concrete present-tense justification +- [ ] Every pattern applied (bounded context, aggregate root, value object, sum type, typed ID class) has a one-line "why this, why now" tied to stage +- [ ] No refinement contradicts CLAUDE.md + +If any check fails, revise before writing `refined.md`. + ## Output Write TWO files: -- `docs/design-reviews/[name]/refinements.md` +- `docs/design-reviews/[name]/refinements.md` (must start with Stage Preamble) - `docs/design-reviews/[name]/refined.md` After writing both files, return exactly: `FINISHED`