Design Independently to Prevent Slops
Overview
Independent design means software artifacts serve the system that will run them, not the conversation that produced them. The test is: would an independent human engineer, planning and programming for themselves, design this the same way?
Follow this sequence: list the requested elements, identify the core engineering need, then implement for the real domain.
When to Use
- A design introduces names, structures, or metadata that echo the conversation instead of the domain.
- An element has no current consumer, behavioral effect, user surface, or persistence purpose.
- Verification proves shape, wording, or apparent completeness rather than behavior through the system surface.
- The result seems optimized for satisfying a plan or reviewer checklist more than for serving the running system.
Do not use this to reject normal domain modeling. If a field drives behavior, persistence, validation, routing, permissions, or user output, keep it.
Workflow
Keep the steps independent and in order. Start with what was requested, then test it against runtime behavior.
1. Enumerate requested elements → what was asked for
2. Classify each element → runtime behavior, user surface, persistence, or dependent artifact
3. Apply the independent-engineer test → would this exist without the request wording?
4. Delete or rename dependent elements → prefer domain names and single sources of truth
5. Replace static tests → test behavior through the surface, not copied structure
6. Re-check the design → every artifact has a current consumer or domain purpose
Dependent-Design Patterns
Common manifestations, not an exhaustive list:
| Pattern |
Smell |
Better move |
| Conversation-shaped naming |
managerDashboardAccess, safeCheckoutStepName, or SarahsDashboard encode request context |
Name the domain behavior: canViewAggregateMetrics, checkoutStepId, teamMetricsView |
| UI-flow API design |
POST /checkout/review-and-confirm mirrors one screen flow |
Model the domain action: POST /orders or POST /payments/confirm |
| Implementation-shaped observability |
Metrics like redis_cache_hits or postgres_query_time leak current storage choices |
Track stable behavior: cache_hits, storage_query_duration, unless the technology is the contract |
| Deployment-shaped config |
awsLambdaTimeout or k8sReplicaCount appears before the product depends on that platform |
Use current concepts: requestTimeout, instanceCount; specialize only when variation exists |
| Design-only metadata |
suggestedFeatures, advisoryFlags, or explanatory notes never affect behavior |
Put prose in docs, or wire metadata to an actual decision |
| Relationship without use |
relatedItems, references, or allowedTransitions no code traverses |
Remove, or implement the routing/validation that needs it |
| Structure-only tests |
Tests assert exact headings, counts, object keys, or non-empty arrays |
Test behavior through the surface |
| Checklist helpers |
One-line wrappers or API methods with no semantic compression |
Use direct access, or create one meaningful operation |
Runtime Gates
Before adding any element, answer:
| Gate |
Required evidence |
| Consumer |
What code reads this outside its definition/test? |
| Decision |
Does it change a branch, route, permission, selection, validation, output, or persisted data? |
| Variation |
Can it vary meaningfully today? |
| Domain name |
Would this name make sense without knowing the request context? |
| Single source |
Are repeated representations derived from one authoritative artifact? |
| Test value |
Would the test fail if behavior broke, not just if copy changed? |
If the answer is “no” or “maybe later,” do not encode it as production structure. Keep the design independent: current consumers, current domain language, current behavior.
Test Rules
Bad tests prove generated structure exists:
expect(config.validationRules).toBeDefined()
expect(document.sections.length).toBeGreaterThan(0)
expect(Object.keys(response)).toContain("metadata")
Good tests drive the real surface:
const result = validateCheckout({ paymentMethod: "expired-card" })
expect(result.canSubmit).toBe(false)
expect(result.errors).toContain("payment-method-expired")
Static text checks are acceptable only when the exact text is the product surface or compatibility contract.
Common Rationalizations
| Rationalization |
Reality |
| "The request mentioned this field/name." |
User wording is input, not the domain model. |
| "This keeps us future-proof." |
Future-proofing without a current consumer is speculative generality. |
| "The structure enforces consistency." |
Consistent unused structure is still unused structure. |
| "The tests cover every requested item." |
Shape coverage is not behavioral confidence. |
| "The deadline requires proving completeness." |
Completeness means the system works through its surface, not that every requested heading or field exists. |
| "It documents intent." |
Documentation belongs in docs/comments unless the program consumes it. |
| "It is harmless." |
Extra schema fields, fixtures, tests, and names create drift and maintenance cost. |
| "It is a public or internal contract." |
Keep it only if a current consumer exists; otherwise it is speculative contract design. |
| "It will support future behavior." |
Write the behavior first, then the schema/test that protects it. Future scaffolding is still future-proofing. |
| "It helps observability or debugging." |
Observability data must be emitted, queried, or displayed. Undisplayed metadata is not observability. |
Red Flags
- Adding an element because the request used a phrase.
- Naming artifacts after a requestor, team, UI step, deployment platform, or current vendor instead of domain behavior.
- Creating metadata and immediately describing it as “advisory,” “informational,” or “non-enforcing.”
- Writing tests that would pass with hardcoded fixtures.
- Manually repeating the same concept across multiple representations instead of deriving one from another.
- Naming artifacts after conversation or process vocabulary rather than domain concepts.
- Adding one-line helpers because a checklist said to provide them.
- Calling unused fields contracts, scaffolding, debugging data, or observability without showing the consumer.
When a red flag appears, stop and re-enumerate: what real runtime behavior is this artifact supposed to serve?
1---2name: slop-design3description: Use when designing/planning for implementation, and to reflect on your design's domain behavior and real consumers.4license: CC-BY-NC-4.05---67# Design Independently to Prevent Slops89## Overview1011Independent design means software artifacts serve the system that will run them, not the conversation that produced them. The test is: **would an independent human engineer, planning and programming for themselves, design this the same way?**1213Follow this sequence: list the requested elements, identify the core engineering need, then implement for the real domain.1415## When to Use1617- A design introduces names, structures, or metadata that echo the conversation instead of the domain.18- An element has no current consumer, behavioral effect, user surface, or persistence purpose.19- Verification proves shape, wording, or apparent completeness rather than behavior through the system surface.20- The result seems optimized for satisfying a plan or reviewer checklist more than for serving the running system.2122Do not use this to reject normal domain modeling. If a field drives behavior, persistence, validation, routing, permissions, or user output, keep it.2324## Workflow2526Keep the steps independent and in order. Start with what was requested, then test it against runtime behavior.2728```291. Enumerate requested elements → what was asked for302. Classify each element → runtime behavior, user surface, persistence, or dependent artifact313. Apply the independent-engineer test → would this exist without the request wording?324. Delete or rename dependent elements → prefer domain names and single sources of truth335. Replace static tests → test behavior through the surface, not copied structure346. Re-check the design → every artifact has a current consumer or domain purpose35```3637## Dependent-Design Patterns3839Common manifestations, not an exhaustive list:4041| Pattern | Smell | Better move |42|---|---|---|43| Conversation-shaped naming | `managerDashboardAccess`, `safeCheckoutStepName`, or `SarahsDashboard` encode request context | Name the domain behavior: `canViewAggregateMetrics`, `checkoutStepId`, `teamMetricsView` |44| UI-flow API design | `POST /checkout/review-and-confirm` mirrors one screen flow | Model the domain action: `POST /orders` or `POST /payments/confirm` |45| Implementation-shaped observability | Metrics like `redis_cache_hits` or `postgres_query_time` leak current storage choices | Track stable behavior: `cache_hits`, `storage_query_duration`, unless the technology is the contract |46| Deployment-shaped config | `awsLambdaTimeout` or `k8sReplicaCount` appears before the product depends on that platform | Use current concepts: `requestTimeout`, `instanceCount`; specialize only when variation exists |47| Design-only metadata | `suggestedFeatures`, `advisoryFlags`, or explanatory `notes` never affect behavior | Put prose in docs, or wire metadata to an actual decision |48| Relationship without use | `relatedItems`, `references`, or `allowedTransitions` no code traverses | Remove, or implement the routing/validation that needs it |49| Structure-only tests | Tests assert exact headings, counts, object keys, or non-empty arrays | Test behavior through the surface |50| Checklist helpers | One-line wrappers or API methods with no semantic compression | Use direct access, or create one meaningful operation |5152## Runtime Gates5354Before adding any element, answer:5556| Gate | Required evidence |57|---|---|58| Consumer | What code reads this outside its definition/test? |59| Decision | Does it change a branch, route, permission, selection, validation, output, or persisted data? |60| Variation | Can it vary meaningfully today? |61| Domain name | Would this name make sense without knowing the request context? |62| Single source | Are repeated representations derived from one authoritative artifact? |63| Test value | Would the test fail if behavior broke, not just if copy changed? |6465If the answer is “no” or “maybe later,” do not encode it as production structure. Keep the design independent: current consumers, current domain language, current behavior.6667## Test Rules6869Bad tests prove generated structure exists:7071```ts72expect(config.validationRules).toBeDefined()73expect(document.sections.length).toBeGreaterThan(0)74expect(Object.keys(response)).toContain("metadata")75```7677Good tests drive the real surface:7879```ts80const result = validateCheckout({ paymentMethod: "expired-card" })81expect(result.canSubmit).toBe(false)82expect(result.errors).toContain("payment-method-expired")83```8485Static text checks are acceptable only when the exact text is the product surface or compatibility contract.8687## Common Rationalizations8889| Rationalization | Reality |90|---|---|91| "The request mentioned this field/name." | User wording is input, not the domain model. |92| "This keeps us future-proof." | Future-proofing without a current consumer is speculative generality. |93| "The structure enforces consistency." | Consistent unused structure is still unused structure. |94| "The tests cover every requested item." | Shape coverage is not behavioral confidence. |95| "The deadline requires proving completeness." | Completeness means the system works through its surface, not that every requested heading or field exists. |96| "It documents intent." | Documentation belongs in docs/comments unless the program consumes it. |97| "It is harmless." | Extra schema fields, fixtures, tests, and names create drift and maintenance cost. |98| "It is a public or internal contract." | Keep it only if a current consumer exists; otherwise it is speculative contract design. |99| "It will support future behavior." | Write the behavior first, then the schema/test that protects it. Future scaffolding is still future-proofing. |100| "It helps observability or debugging." | Observability data must be emitted, queried, or displayed. Undisplayed metadata is not observability. |101102## Red Flags103104- Adding an element because the request used a phrase.105- Naming artifacts after a requestor, team, UI step, deployment platform, or current vendor instead of domain behavior.106- Creating metadata and immediately describing it as “advisory,” “informational,” or “non-enforcing.”107- Writing tests that would pass with hardcoded fixtures.108- Manually repeating the same concept across multiple representations instead of deriving one from another.109- Naming artifacts after conversation or process vocabulary rather than domain concepts.110- Adding one-line helpers because a checklist said to provide them.111- Calling unused fields contracts, scaffolding, debugging data, or observability without showing the consumer.112113When a red flag appears, stop and re-enumerate: what real runtime behavior is this artifact supposed to serve?
Arcadi4