OBS-07: Intent-over-prescription principle for agent definitions

[b-coman]

Origin

E2E Round 3, OBS-07 — Design Gap, Medium severity (see reports/e2e-003-ido4shape-cloud.md lines 231–350).

Surfaced during Phase 2 output review: sampled 7 task descriptions across INFRA, PLAT, STOR, and PLUG capabilities. The technical-spec-writer rules produce consistently over-prescriptive task descriptions. Implementer agents consuming these tasks would have essentially zero room to exercise judgment.

Problem

Over-prescription makes implementation tasks mechanical. The implementer agent becomes a typist: "create file X with function Y with signature Z" leaves no room for design decisions that might surface problems the spec didn't anticipate.

Evidence from sampled tasks

Pattern 1: File paths and function signatures fully dictated.

"Create apps/api/src/storage/gcs.ts exposing readFile(orgId, projectId, filename, generation?) and writeFile(orgId, projectId, filename, content) that returns the new generation number." — STOR-01A

Pattern 2: Directory structures enumerated.

"scaffold apps/api/src/ with: index.ts entry point, routes/ directory, services/, db/, storage/, auth/, notifications/, jobs/" — PLAT-01B

Pattern 3: Config values and algorithms pinned.

"exponential backoff 5s, 10s, 20s, 40s, ... max 5min" — PLUG-02B
"SHA-256 of a canonical serialization" — STOR-01B

Pattern 4: "Decisions" pre-made in parentheses.

"Decide between Hono and Fastify (Hono preferred for Cloud Run cold-start friendliness)" — PLAT-01B

Pattern 5 (good): Intent-based elements exist but are sparse.

"the most likely place for a security bug" — PLAT-01D (flags risk, doesn't dictate code)
"Pull-to-prompt latency is under 5 seconds" — PLUG-02C (constraint, not implementation)

The distinguishing heuristic

"Would an implementer changing this decision have cross-capability impact, violate a stated constraint, or conflict with a canvas-decided approach? If YES, include it as a constraint. If NO, leave it to the implementer."

Necessary prescription (include)	Accidental prescription (leave out)
Architectural constraints affecting multiple capabilities	Writer's implementation preference
Shared contracts other capabilities depend on	Reasonable defaults dressed as requirements
Canvas-decided approaches after research	Method signatures without cross-capability impact
Hard integration points	Directory names, file organization
Security/tenancy patterns that must not be bypassed	Library choices when no canvas decision exists

Fix approach — principle + examples, not rule lists

An earlier version proposed 3 rule additions per agent + include/exclude lists. That was itself over-prescriptive — exactly the failure mode this OBS flags. See OBS-09 (#2) for the meta-concern. The right fix is a principle + concrete examples.

For agents/technical-spec-writer.md — 1 new principle + 1 example block

Principle:

Specify intent and constraints, not implementation. If an implementer changing a decision would have cross-capability impact or violate a stated constraint, the decision belongs in the task description. If not, the implementer agent decides. Under-specification is recoverable; over-prescription is not. When in doubt, leave it out.

Example block:

BAD (over-prescriptive):
  Create `apps/api/src/storage/gcs.ts` exposing
  `readFile(orgId, projectId, filename, generation?)` and
  `writeFile(orgId, projectId, filename, content)` that returns
  the generation number. Uses @google-cloud/storage.

GOOD (intent-based):
  Add the application-side GCS client wrapper that other STOR
  capabilities build on. Must be tenant-aware (org_id as path
  prefix), read/write only (no delete — IAM enforced), and
  support streaming up to the VIEW-01 10MB file bound.
  Anchor: existing tenant-aware repo pattern in apps/api/src/db/repo.ts.

WHAT MOVED: file paths, function signatures, library choice, and
return types are implementation decisions that an implementer can
make without cross-capability impact. The constraints — tenant-
awareness, read/write only, 10MB streaming — are what the rest of
STOR depends on and must be preserved.

For agents/code-analyzer.md — 1 new principle (with inline example)

Complexity Assessment describes what makes the work hard and what it depends on, not how to solve it. Good: "STOR-05's 1-hour TTL refresh path must handle concurrent writes — the existing session-start.sh hook gives the right granularity but refreshing on every turn is unusual for Bash." Bad: "Use Postgres row-level locks with SELECT FOR UPDATE NOWAIT...". The first frames the hard problem; the second tells Phase 2 what code to produce.

Connection to the refinement skill (OBS-06, #5)

This finding strengthens OBS-06's value proposition. The intent-vs-prescription balance is hard to fully resolve in rules alone — what counts as "over-prescriptive" depends on the task, the team, and the implementer agents. Principles point in the right direction; the user's judgment during refinement is where calibration happens.

Deliverables

• agents/technical-spec-writer.md — 1 new principle + 1 example block added to Rules section
• agents/code-analyzer.md — 1 new principle with inline example added to Rules section
• Principles land INTO the audited rule set (after OBS-09: Rule audit across agents and decompose skills #2 completes), not on top of the pre-audit version

Acceptance criteria

• Principle text is concise (2-3 sentences max, not a paragraph)
• Example block shows BAD → GOOD → WHAT MOVED pattern
• No forbidden-term list, no include/exclude table, no rule enumeration added
• Consistent with prompt strategy doc (Prompt strategy doc — cross-suite governance for skill/agent/prompt authoring #1) principles

Calibration baseline

The current Phase 2 technical spec at /Users/bogdanionutcoman/dev-projects/ido4shape-cloud/specs/ido4shape-enterprise-cloud-technical.md (1317 lines, 94 tasks, 29 capabilities) is the "before" baseline. Specific sampled tasks: PLAT-01A, PLAT-01B, PLAT-01D, STOR-01A, STOR-01B, PLUG-02A, PLUG-02B, PLUG-02C.

Round 5 calibration: re-run decomposition on same strategic spec, compare these same tasks. Expect shorter descriptions, more outcomes framed as constraints, fewer dictated file paths and signatures.

Dependencies

• Blocked by: OBS-09: Rule audit across agents and decompose skills #2 (OBS-09 rule audit — principles land into audited rule set)
• Blocks: OBS-06: Build unified decompose-refine skill (canvas mode + technical-spec mode) #5 (OBS-06 decompose-refine skill references these principles)

References

• reports/e2e-003-ido4shape-cloud.md — OBS-07 (lines 231–350), evidence (lines 238–273), heuristic (lines 275–287), fix approach (lines 289–350)
• agents/technical-spec-writer.md — Rules section (lines 211–219)
• agents/code-analyzer.md — Rules section (lines 178–187)
• Round 3 technical spec baseline: ido4shape-cloud/specs/ido4shape-enterprise-cloud-technical.md