Skip to content

Add stage-awareness rules to Refiner agent#26

Open
digitalgrove-bit wants to merge 1 commit into
NTCoding:mainfrom
digitalgrove-bit:refiner-stage-awareness
Open

Add stage-awareness rules to Refiner agent#26
digitalgrove-bit wants to merge 1 commit into
NTCoding:mainfrom
digitalgrove-bit:refiner-stage-awareness

Conversation

@digitalgrove-bit
Copy link
Copy Markdown

Summary

Adds a mandatory stage-awareness check to the Refiner agent so it stops over-engineering MVPs.

Motivation

In its current form, the Refiner applies SoC and tactical-DDD patterns without regard to project stage, team size, or existing layout. In one real case, it produced a design with:

  • 3× file count growth (~12 → ~40 files)
  • Two new bounded contexts
  • Typed UUID classes
  • Aggregate roots over single tables
  • CQRS-style read ports

…all for a solo-developer, pre-customer project. The Critique agent rejected nearly all of it (4 CRITICAL + 10 HIGH + 10 MEDIUM + 8 LOW findings). The over-engineering wasn't a Critique failure — the Refiner had no instruction to ask "is this stage-appropriate?" before applying the patterns.

What this changes

Adds a ## Stage-Awareness (MANDATORY before proposing refinements) section to architect-refine-critique/agents/refiner.md with four steps:

  1. Read project context — CLAUDE.md and docs/prd.md to extract team size and stage; scan existing codebase layout.
  2. Write a Stage Preamble at the top of refinements.md declaring team size, stage, existing layout, and any conflicts.
  3. Apply three constraint rules:
    • R-1: No new layout conventions without explicit request (don't retrofit features/platform/shell onto a flat app/)
    • R-2: 50% file-count growth budget — each excess file needs a concrete present-tense justification, not "this scales better"
    • R-3: Match patterns to stage (pre-customer/MVP → flat modules, plain dataclasses, single-file aggregates; scaling → aggregates and value objects; mature → full DDD toolkit)
  4. Self-check before writing refined.md.

Default bias: when in doubt about stage, do less. The Critique agent flags under-engineering as readily as over-engineering, and adding structure later is cheaper than ripping it out.

Why this fits the chain

The Architect → Refine → Critique chain works because each agent has a clear job. Adding stage-awareness to the Refiner doesn't change its responsibility — it constrains the search space the Refiner explores. The Critique agent still has the final word; it just has less to push back on when the Refiner stays in scope.

Test plan

  • Run /arc on a solo-developer pre-customer project; confirm refinements.md opens with a Stage Preamble and respects R-1/R-2/R-3.
  • Run /arc on a project with CLAUDE.md declaring team size; confirm Refiner extracts and uses that signal.
  • Run /arc on a project with an existing features/platform/shell layout; confirm Refiner doesn't propose alternative layouts.

Notes

This change has been running locally in production for a week without regression. Happy to iterate on wording or scope if you'd prefer a lighter touch.

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) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant