shaping

name	shaping
description	Collaborative Shaping with the Architect: capture requirements, boundaries, shapes, fit checks, research unknown mechanics, and transition to Modeling then Slicing. TRIGGER when the Architect asks to shape, scope, compare approaches, or turn a rough idea into a modeled change.

Shaping

• Shaping defines the problem and compares shapes before Execution.
• Shaping is the first part of Shaping → Modeling → Slicing.
• Requirements, boundaries, and shapes can change each other in any order; every checkpoint shows the current state of all three.
• CURRENT is the reserved shape name for the existing system.

1. Start from the Architect's entry point

Offer the two valid starts

Start from requirements when the Architect describes pain and wants shapes to emerge. Start from a shape when the Architect sketches a path and requirements need to be extracted. Example: "from R" means describe the pain first. "from S" means sketch a shape first.

Match the energy level

Broad refactor energy earns broader Architecture options. Careful adjustment energy stays focused. When cutting scope, the remaining shape must still beat what Users have now.

2. Maintain requirements as R

R states what is needed

Use R0, R1... for the problem space. R is negotiated with the Architect, not auto-filled by the Agent. R says what must be true, not which shape satisfies it.

Keep top-level R readable

Use no more than nine top-level Rs. Group overflow as R3.1, R3.2.

Template:

| R | Requirement | Status |
|---|-------------|--------|
| R0 | Core Goal | Core Goal |
| R1 | User can return to the same search state | Must-have |
| R2 | Search survives page refresh | Nice-to-have |

3. Maintain boundaries as X

X is a firm no

Use X0, X1... for what this work does not cover. Boundaries are specific and testable. Example: no public API changes; no migrations. Never: keep it simple; do not break anything.

IF an R conflicts with an X:

Surface the conflict instead of dropping either side

Stop and renegotiate. Do not silently remove the R or boundary.

4. Maintain shapes as S

Shapes are mutually exclusive approaches

Use A, B, and C for approaches where the Architect picks one. Give each shape a short title that captures the approach. Example: C: Two data sources with hybrid pagination.

Components combine within a shape

Use C1, C2 for parts that compose inside a selected shape. Use C3-A, C3-B for alternatives inside a component. Example: Shape E = C1 + C2 + C3-A.

Preserve notation as an audit trail

Do not renumber old parts just to make the table prettier. The notation shows what changed across iterations.

5. Write shape parts as mechanisms

Parts describe what changes

A part names the thing built or changed. It does not restate intent, boundary, or R. Example: B1: Signing handler — includes WaiverSignatures table + handler. Never: B4: Data model.

Parts are vertical

Co-locate the data model with the feature it serves. Extract shared logic into a standalone part that other parts reference. Example: B1: Signing handler, then B2 → calls B1 and B3 → calls B1.

Add hierarchy only when flat stops working

Start with E1, E2. Use E1.1 only when there are too many parts or the final file layout must be shown.

Name Precedent on selected parts

Each selected shape part names the existing file or system it builds on, with its path, or the research proving none exists.

6. Run the fit check

The fit check decides which shape to pursue

Use one table: requirements as rows, shapes as columns.

Template:

| R | Requirement | A | B | C |
|---|-------------|:-:|:-:|:-:|
| R0 | Core Goal text | ✅ | ✅ | ❌ |
| R1 | Full requirement text | ❌ | ✅ | ✅ |

Shape columns are binary

Use ✅ or ❌ only in shape columns. Put short explanations in a minimal Notes section below the table.

Unknown mechanics fail the fit check

A flagged unknown means the WHAT is described but the HOW is not. The shape is ❌ until the unknown is researched and cleared by a Decision. Never: mark ⚠️ as passing.

IF a shape passes every R but still feels wrong:

Name the missing R and rerun the fit check

The discomfort means the table is missing a requirement.

7. Research unknown mechanics

IF mechanics or feasibility are uncertain:

Dispatch one researcher Subagent per unknown

Research learns how the existing system works and what it would take to build a part before proposing it. Dispatch multiple researcher Subagents in parallel when multiple unknowns exist.

Research acceptance names understanding, not a Decision

Acceptance says what the Agent will be able to describe after research. The Decision clears the flag afterward; the research does not. Example: we can describe how Users set their language. Never: whether this is a blocker.

8. Surface every checkpoint

Show the full current state

After any iteration that changes R, X, shapes, fit checks, or Modeling, present requirements and statuses, boundaries, outstanding Decisions, and what changed.

Mark changed cells

Use 🟡 on every table cell that changed since the previous checkpoint. Show every R, every shape part including sub-parts, and every alternative.

9. Transition to Modeling and Slicing

Keep Prompt levels consistent

Shaping Prompt holds R, X, shapes, and fit checks. Slices Prompt holds Slice definitions. Slice Plans hold implementation detail. A change at any level ripples both ways; update every affected level in the same operation.

IF a shape is selected and the fit check passed:

Invoke /modeling

Model the selected shape into Affordances before Slicing.

IF Modeling is complete:

Invoke /slicing

Break the modeled change into vertical Slices. Every Slice ends in demo-able functionality.

References

• Writing Shaping Prompt files, source capture, file layout, frontmatter, and research Prompts → documents.md
• Running a high-level Addressed and Answered fit check for chunked requirements and mostly-unknown shapes → macro-fit-check.md