Strengthen Design/Implement boundary and add explicit Subject & Scope to all prompts

[Copilot]

The 4dc prompts lacked explicit scoping instructions and clear separation between Design (architectural decisions) and Implement (concrete steps), leading to potential scope creep and contract redefinition across phases.

Changes

All main-phase prompts

• Added explicit "Subject & Scope" sections instructing LLMs to read/reason only within the project root at path
• Self-contained; no runtime dependency on templates/RULES.md
• Reinforced STOP 2 gates to prevent generating final artifacts before explicit approval

design.prompt.md

• Added "Artifact-focused (not steps)" style guidance
• Explicitly prohibits: file paths, per-file actions, chronological sequences, task lists, PR groupings
• Testing/CI/observability expressed as constraints and targets, not step-by-step instructions
  • ✅ "must support rollback via feature flag", "must log request IDs"
  • ❌ "Step 1: Add feature flag to config.yml", "Step 2: Create test_rollback.go"
• Acceptance criteria forbids file/action/step lists; requires behavior-level test strategy

implement.prompt.md

• Explicitly forbids inventing new interfaces, data shapes, or contracts not specified in design.md
• Treats design.md as authoritative; flags incomplete contracts as risks rather than silently creating new ones
• Reinforces stable contract adherence in Phase 3 writing guidance

README.md

• Clarifies Design produces specs/contracts, Implement produces concrete file-level steps
• Explains handoff: Design defines "what components do and how they interact"; Implement defines "which files to touch and what to change"

Example of strengthened boundary:

# Before: Design could produce
- Add feature flag config
- Create rollback test
- Update deployment pipeline

# After: Design produces
- Rollback constraint: must support disabling via feature flag
- Testing target: verify behavior with flag enabled/disabled
- CI constraint: deployment must validate flag state

# Implement then produces concrete steps
- Step 1: Add `enable_feature_x: bool` to `config/features.yml`
- Step 2: Update `internal/app/features.go` to check flag
- Step 3: Add test cases in `internal/app/features_test.go`

Net change: +76 lines, -12 lines across 5 files.

Original prompt

Update 4dc prompt templates and README to clarify Design vs Implement boundaries, add explicit Subject & Scope sections, and reinforce STOP gates and artifact rules per templates/RULES.md.

Context

• Repository: co0p/4dc
• Goal: Improve separation of concerns across the four-document cascade prompts (increment, design, implement, improve) and README, ensuring they explicitly adhere to templates/RULES.md.
• Source files provided:
  • README.md (commit 8e61d62)
  • design.prompt.md
  • implement.prompt.md
  • increment.prompt.md
  • improve.prompt.md
  • rules reference is templates/RULES.md

Requirements (derived from RULES.md and user feedback)

1. Scope & Subject

• Each main-phase prompt must explicitly state the subject scope and instruct the LLM to read and reason only within that scope.
• Prompts must be self-contained and not depend on RULES.md at runtime.

2. Design vs Implement Separation

• Design prompt:
  • Produce artifacts/specifications (interfaces, data shapes, invariants, test strategy, observability targets, rollout/rollback constraints).
  • Explicitly prohibit file paths, per-file actions, chronological step sequences, task lists, PR groupings, and pipeline step instructions.
  • Express CI/CD and observability as constraints/targets, not steps.
• Implement prompt:
  • Consume design artifacts without redefining them.
  • Explicitly state: do not invent new contracts/interfaces/data shapes not in design.md; flag gaps as risks or follow-up increments.

3. STOP Gates and Confirmation

• Ensure STOP 1 and STOP 2 are present and explicit in all prompts; do not generate final artifacts before explicit YES at STOP 2.

4. Artifact Hygiene and Output Structure

• Reinforce that final artifacts do not mention prompts/LLMs.
• Strengthen acceptance criteria for Design to forbid file/action/step lists; for Implement to forbid redefining contracts.
• README should explain the handoff between Design (specs/contracts) and Implement (concrete steps/tests) to make boundaries clear.

Changes to apply

• README.md: Add clarifying paragraphs under “Design – HOW” and “Implement – STEPS” detailing artifacts, prohibitions, and handoff.
• design.prompt.md:
  • Add a “Subject & Scope (Explicit)” section reinforcing scoped reading.
  • Enhance Style with “Artifact-focused (not steps)”.
  • Strengthen “Stay at the Design Level, Not Implementation Tasks” to explicitly prohibit file paths, per-file actions, chronological sequences, and PR grouping.
  • In Process STOP 2 outline, specify expressing testing/CI/observability as constraints/behaviors, not steps or file-level directives.
  • Update Acceptance Criteria to forbid file/action/step lists and keep test strategy at behavior/coverage level.
  • In Output sections, reiterate avoiding naming exact test files or step sequences.
• implement.prompt.md:
  • Add a “Subject & Scope (Explicit)” section.
  • In Goal, add bullets stating not to invent new contracts; treat design.md as authoritative for interfaces/data shapes.
  • In Phase 3 writing guidance, add reinforcement to keep contracts stable and raise mismatches as risks.
• increment.prompt.md and improve.prompt.md:
  • Add a brief “Subject & Scope (Explicit)” reminder consistent with RULES.md (they already mostly do this) and restate “do not generate final artifacts before STOP 2 approval.”

Acceptance

• All prompts remain self-contained, include STOP gates, and adhere to templates/RULES.md without referencing it at runtime.
• README explains artifact handoff and boundaries.
• No changes introduce mentions of prompts/assistants in output artifacts.

Deliverables

• A single pull request updating the above files with the described edits.

This pull request was created as a result of the following prompt from Copilot chat.

Update 4dc prompt templates and README to clarify Design vs Implement boundaries, add explicit Subject & Scope sections, and reinforce STOP gates and artifact rules per templates/RULES.md.

Context

• Repository: co0p/4dc
• Goal: Improve separation of concerns across the four-document cascade prompts (increment, design, implement, improve) and README, ensuring they explicitly adhere to templates/RULES.md.
• Source files provided:
  • README.md (commit 8e61d62)
  • design.prompt.md
  • implement.prompt.md
  • increment.prompt.md
  • improve.prompt.md
  • rules reference is templates/RULES.md

Requirements (derived from RULES.md and user feedback)

1. Scope & Subject

• Each main-phase prompt must explicitly state the subject scope and instruct the LLM to read and reason only within that scope.
• Prompts must be self-contained and not depend on RULES.md at runtime.

2. Design vs Implement Separation

• Design prompt:
  • Produce artifacts/specifications (interfaces, data shapes, invariants, test strategy, observability targets, rollout/rollback constraints).
  • Explicitly prohibit file paths, per-file actions, chronological step sequences, task lists, PR groupings, and pipeline step instructions.
  • Express CI/CD and observability as constraints/targets, not steps.
• Implement prompt:
  • Consume design artifacts without redefining them.
  • Explicitly state: do not invent new contracts/interfaces/data shapes not in design.md; flag gaps as risks or follow-up increments.

3. STOP Gates and Confirmation

• Ensure STOP 1 and STOP 2 are present and explicit in all prompts; do not generate final artifacts before explicit YES at STOP 2.

4. Artifact Hygiene and Output Structure

• Reinforce that final artifacts do not mention prompts/LLMs.
• Strengthen acceptance criteria for Design to forbid file/action/step lists; for Implement to forbid redefining contracts.
• README should explain the handoff between Design (specs/contracts) and Implement (concrete steps/tests) to make boundaries clear.

Changes to apply

• README.md: Add clarifying paragraphs under “Design – HOW” and “Implement – STEPS” detailing artifacts, prohibitions, and handoff.
• design.prompt.md:
  • Add a “Subject & Scope (Explicit)” section reinforcing scoped reading.
  • Enhance Style with “Artifact-focused (not steps)”.
  • Strengthen “Stay at the Design Level, Not Implementation Tasks” to explicitly prohibit file paths, per-file actions, chronological sequences, and PR grouping.
  • In Process STOP 2 outline, specify expressing testing/CI/observability as constraints/behaviors, not steps or file-level directives.
  • Update Acceptance Criteria to forbid file/action/step lists and keep test strategy at behavior/coverage level.
  • In Output sections, reiterate avoiding naming exact test files or step sequences.
• implement.prompt.md:
  • Add a “Subject & Scope (Explicit)” section.
  • In Goal, add bullets stating not to invent new contracts; treat design.md as authoritative for interfaces/data shapes.
  • In Phase 3 writing guidance, add reinforcement to keep contracts stable and raise mismatches as risks.
• increment.prompt.md and improve.prompt.md:
  • Add a brief “Subject & Scope (Explicit)” reminder consistent with RULES.md (they already mostly do this) and restate “do not generate final artifacts before STOP 2 approval.”

Acceptance

• All prompts remain self-contained, include STOP gates, and adhere to templates/RULES.md without referencing it at runtime.
• README explains artifact handoff and boundaries.
• No changes introduce mentions of prompts/assistants in output artifacts.

Deliverables

• A single pull request updating the above files with the described edits.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.