From e6242bda96b31180f8adf9127c1ad6a28e0aec93 Mon Sep 17 00:00:00 2001
From: Rodrigo Haertel <rodrigo.haertel@twism.com>
Date: Sat, 4 Apr 2026 16:52:14 -0300
Subject: [PATCH 1/7] feat: add ce:prototype skill for assumption validation
 before planning

Adds a new skill that sits between ce:brainstorm and ce:plan in the
compound workflow. ce:prototype builds throwaway prototypes to validate
untested assumptions (APIs, data sources, UX patterns, integrations)
before committing to an implementation plan.

Key design decisions:
- Validation goals defined upfront, AI-suggested from requirements
- Scope classified as Lightweight/Standard/Deep with effort alignment
- Speed over quality, but never fake what you're testing
- User testing is explicit for subjective goals (waits for feedback)
- Output is a durable validation report in docs/prototypes/
- Prototype code is deleted after report is written

Also adds "Prototype first" as a handoff option in ce:brainstorm's
Phase 4 when requirements contain unverified external dependencies.

New files:
- skills/ce-prototype/SKILL.md
- skills/ce-prototype/assets/validation-report-template.md
- skills/ce-prototype/references/validation-report-schema.md

Modified:
- skills/ce-brainstorm/SKILL.md (added prototype handoff option)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../ce-brainstorm/references/handoff.md       |   6 +
 .../skills/ce-prototype/SKILL.md              | 270 ++++++++++++++++++
 .../assets/validation-report-template.md      |  72 +++++
 .../references/validation-report-schema.md    |  59 ++++
 4 files changed, 407 insertions(+)
 create mode 100644 plugins/compound-engineering/skills/ce-prototype/SKILL.md
 create mode 100644 plugins/compound-engineering/skills/ce-prototype/assets/validation-report-template.md
 create mode 100644 plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md

diff --git a/plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md b/plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md
index effefc721..5368e4f6c 100644
--- a/plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md
+++ b/plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md
@@ -20,6 +20,7 @@ If `Resolve Before Planning` contains any items:
 
 Present only the options that apply:
 - **Proceed to planning (Recommended)** - Run `/ce:plan` for structured implementation planning
+- **Prototype first** - Run `/ce:prototype` to validate untested assumptions before planning. Offer this when the requirements depend on unverified external factors (third-party APIs, data source quality, UX patterns, integration behavior) that could invalidate the plan if wrong. Do not offer when all requirements are grounded in known, verified constraints.
 - **Proceed directly to work** - Only offer this when scope is lightweight, success criteria are clear, scope boundaries are clear, and no meaningful technical or research questions remain
 - **Run additional document review** - Offer this only when a requirements document exists. Runs another pass for further refinement
 - **Ask more questions** - Continue clarifying scope, preferences, or edge cases
@@ -27,6 +28,7 @@ Present only the options that apply:
 - **Done for now** - Return later
 
 If the direct-to-work gate is not satisfied, omit that option entirely.
+If the prototype gate is not satisfied (no unverified external dependencies), omit that option entirely.
 
 #### 4.2 Handle the Selected Option
 
@@ -34,6 +36,10 @@ If the direct-to-work gate is not satisfied, omit that option entirely.
 
 Immediately run `/ce:plan` in the current session. Pass the requirements document path when one exists; otherwise pass a concise summary of the finalized brainstorm decisions. Do not print the closing summary first.
 
+**If user selects "Prototype first":**
+
+Immediately run `/ce:prototype` in the current session. Pass the requirements document path when one exists. The prototype skill will extract testable assumptions from the requirements, validate them, and produce a validation report that feeds into `/ce:plan`. Do not print the closing summary first.
+
 **If user selects "Proceed directly to work":**
 
 Immediately run `/ce:work` in the current session using the finalized brainstorm output as context. If a compact requirements document exists, pass its path. Do not print the closing summary first.
diff --git a/plugins/compound-engineering/skills/ce-prototype/SKILL.md b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
new file mode 100644
index 000000000..e5aa4811d
--- /dev/null
+++ b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
@@ -0,0 +1,270 @@
+---
+name: ce:prototype
+description: "Build a throwaway prototype to validate assumptions before committing to an implementation plan. Use when the user says 'prototype this', 'let me test this idea first', 'spike on this', 'validate this before planning', 'build a quick prototype', 'I want to test if this works', 'try this out before we plan', 'proof of concept', 'quick test', 'throwaway prototype', or 'validate assumptions'. Also use when a brainstorm or requirements document contains untested assumptions about APIs, data sources, UX patterns, or integrations, or when the user wants to de-risk before planning."
+argument-hint: "[optional: feature description, requirements doc path, or specific assumptions to validate]"
+---
+
+# Prototype: Validate Before You Plan
+
+**Note: The current year is 2026.** Use this when dating validation reports.
+
+`ce:brainstorm` defines **WHAT** to build. `ce:prototype` proves **WHETHER** key assumptions hold. `ce:plan` defines **HOW** to build it.
+
+Prototyping sits between brainstorm and planning because planning without validation is guesswork — a plan might commit to an API that returns unusable data, a UX pattern that feels wrong, or a data source that is unreliable. Discovering this after planning wastes the plan. Discovering it during a quick prototype turns uncertainty into constraints that make the plan stronger.
+
+**This skill does not produce production code.** It produces a throwaway prototype and a durable validation report. The prototype gets deleted. The report feeds into `/ce:plan`.
+
+**IMPORTANT: All file references in generated documents must use repo-relative paths (e.g., `prototypes/stripe-refund-webhooks/`), never absolute paths.**
+
+## Core Principles
+
+1. **Speed over quality** — Use whatever technology is fastest: static HTML, a script, a no-code tool, raw API calls. No linting, no tests, no architecture. The only code standard is "does it answer the validation question?"
+2. **Never fake what you are testing** — If a validation goal is "test image quality from API X," do not mock API X. If unsure whether a shortcut compromises a validation goal, ask the user before proceeding.
+3. **Throwaway by default** — The prototype is scaffolded in an isolated directory and deleted after the validation report is written. If something looks worth keeping, flag it — but reuse is the exception, not the goal.
+4. **Effort-aligned** — Align effort expectations with the user before building. A prototype taking more than one day is likely not a prototype — it is an MVP. Recommend `/ce:plan` instead.
+5. **Goal-driven** — Every prototype has explicit validation goals defined upfront. Building without goals is exploration, not prototyping.
+
+## Interaction Method
+
+Use the platform's blocking question tool when available (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+
+Ask one question at a time. Prefer single-select when natural options exist.
+
+## Feature Description
+
+<feature_description> #$ARGUMENTS </feature_description>
+
+**If the feature description above is empty, ask the user:** "What would you like to prototype? Describe the idea, assumption, or risk you want to validate."
+
+Do not proceed until there is a clear prototyping target.
+
+## Execution Flow
+
+### Phase 0: Source and Context
+
+#### 0.1 Find Upstream Requirements
+
+Search `docs/brainstorms/` for files matching `*-requirements.md`. Apply the same relevance criteria as `ce:plan`: topic match, recency, same problem scope.
+
+If a relevant requirements document exists:
+1. Read it thoroughly
+2. Announce it as the source document for prototyping
+3. Extract testable assumptions — claims about external APIs, data quality, UX patterns, integration behavior, performance characteristics, or user experience that the requirements take for granted but have not been verified
+
+If no requirements document exists, proceed from the user's description directly.
+
+#### 0.2 Check for Existing Prototypes
+
+Search for existing prototype directories (`prototypes/`, `docs/prototypes/`, or similar patterns in the repo). If a previous prototype for the same topic exists, ask the user whether to build on it or start fresh.
+
+### Phase 1: Define Validation Goals
+
+This is the most important phase. A prototype without clear goals is aimless.
+
+#### 1.1 Suggest Validation Goals
+
+Based on the requirements document (or user description), propose 3-5 candidate validation goals. Each goal must be:
+
+- **Specific**: "Test whether the Stripe webhook payload includes refund metadata" not "Test the API"
+- **Binary**: Can be answered proved/disproved/inconclusive
+- **Independent**: Each goal can be tested without depending on others
+
+Organize suggestions by category when useful:
+- **Technical feasibility** — Can this API/service/tool do what we need?
+- **Data quality** — Is the data source good enough?
+- **UX viability** — Does the core interaction feel right?
+- **Integration** — Does this third-party service work as expected?
+- **Performance** — Is it fast enough for the intended use?
+
+Present the suggestions and let the user pick, modify, add, or remove goals. Use multi-select — all selected goals can coexist.
+
+#### 1.2 Classify Scope and Align Effort
+
+Classify the prototype scope based on the selected validation goals:
+
+- **Lightweight** — Single validation goal, simple test (one API call, one static page). Typical effort: 15-30 minutes.
+- **Standard** — 2-3 validation goals, moderate integration work (connect to a real service, build a minimal interactive page). Typical effort: 1-2 hours.
+- **Deep** — 4+ validation goals or multi-service orchestration (end-to-end flow, multiple data sources, complex UX interaction). Typical effort: half day to one day.
+
+After classifying, align effort expectations with the user:
+
+- State the scope classification and expected effort range
+- Ask the user if that matches their expectation
+- If the estimate exceeds half a day, flag it: "This feels larger than a prototype — consider whether `/ce:plan` with a phased approach would serve better"
+- Hard ceiling: if the prototype would take more than one day, recommend splitting into smaller validation rounds or moving to planning
+
+Do not proceed until effort is aligned.
+
+### Phase 2: Scaffold and Build
+
+#### 2.1 Create Isolated Prototype Directory
+
+Scaffold the prototype in an isolated location:
+
+```
+prototypes/
+  <topic-slug>/
+    ... prototype files ...
+```
+
+No project standards apply. No linting, no tests, no architecture. The directory structure should be whatever is fastest for the validation goals.
+
+#### 2.2 Build the Fastest Path
+
+For each validation goal, build the minimum artifact that answers the question:
+
+- **API feasibility** — Raw API calls, dump responses, inspect data
+- **UX viability** — Static HTML page, minimal interactivity, just enough to feel the interaction
+- **Data quality** — Fetch real samples, display or analyze them
+- **Integration** — Connect to the real service, verify behavior
+- **Performance** — Time real operations, measure what matters
+
+**Critical rule:** Before taking a shortcut on any step, evaluate whether it compromises a validation goal. If there is any doubt, ask the user. For example:
+- Hardcoding sample data is fine if the goal is testing UX layout
+- Hardcoding sample data is NOT fine if the goal is testing data source quality
+- Using a placeholder image is fine if testing game mechanics
+- Using a placeholder image is NOT fine if testing image recognition quality
+
+#### 2.3 Validate Each Goal
+
+After building, test each validation goal explicitly. Many goals — especially UX viability, data quality perception, and "does this feel right?" questions — **require the user to interact with the prototype and provide feedback**. Automated checks alone cannot answer whether an image source looks good enough or whether a game mechanic feels fun.
+
+**Classify each goal by validation method:**
+
+- **Automated** — Can be verified programmatically (API response codes, load times, data format checks). Run these directly and record results.
+- **User-tested** — Requires human judgment (visual quality, UX feel, interaction flow, content suitability). For these:
+  1. Present the prototype to the user with clear instructions on what to test
+  2. Ask the user to interact with it (open the HTML file, try the flow, look at the images)
+  3. Wait for the user's feedback before recording a result — do not assume or guess their reaction
+  4. Ask targeted follow-up questions if the feedback is ambiguous (e.g., "You said the images are 'okay' — is that good enough for the MVP, or would you need better quality?")
+
+When in doubt about whether a goal needs user testing, default to asking. Most prototypes exist precisely because there is a subjective judgment call that only a human can make.
+
+For each goal, record:
+- **Status**: Proved / Disproved / Inconclusive
+- **Evidence**: What was observed (screenshots, API responses, measurements, **user feedback quotes**)
+- **Surprises**: Anything unexpected that affects the plan
+- **Constraints discovered**: Rate limits, quality issues, missing features, etc.
+
+### Phase 3: Write Validation Report
+
+Read `assets/validation-report-template.md` for the report structure.
+
+Write the report to `docs/prototypes/<topic-slug>-validation-<date>.md`.
+
+Create `docs/prototypes/` if it does not exist.
+
+The validation report is the durable output — it survives after the prototype code is deleted. It must contain enough detail that `/ce:plan` (or a future reader) can understand what was tested and what was learned without access to the prototype code.
+
+For detailed field descriptions and frontmatter schema, see `references/validation-report-schema.md`.
+
+### Phase 4: Clean Up and Recommend
+
+#### 4.1 Flag Reusable Artifacts
+
+Before cleaning up, scan the prototype for anything worth keeping:
+- Useful API wrapper code
+- Configuration or credentials setup that took effort
+- Static assets (images, sample data) that the MVP will need
+
+If anything is found, flag it to the user with a brief explanation. Let them decide whether to preserve it (by moving it elsewhere) before cleanup.
+
+#### 4.2 Clean Up
+
+Delete the prototype directory. The validation report in `docs/prototypes/` persists.
+
+If the user explicitly asks to keep the prototype, respect that — but note in the validation report that the prototype code still exists and where.
+
+#### 4.3 Recommend Next Step
+
+Based on the validation results, recommend the appropriate next step:
+
+| Result | Recommendation |
+|--------|---------------|
+| All goals proved | Proceed to `/ce:plan` — validated constraints feed directly into planning |
+| Some goals disproved | Revisit requirements with `/ce:brainstorm` — scope or approach may need to change |
+| Inconclusive goals | Run a focused second prototype round on the inconclusive goals |
+| Major surprise discovered | Discuss implications before proceeding — the discovery may reshape the entire approach |
+
+Present as a question using the platform's blocking question tool.
+
+### Phase 5 (Optional): Brainstorm Integration Suggestion
+
+If this prototype was triggered manually (not from a brainstorm recommendation):
+- Check whether a requirements document exists for this topic
+- If it does, suggest updating it with the validated/disproved assumptions
+- If it does not, note that the validation report is self-contained and planning can reference it directly
+
+## Preconditions
+
+<preconditions enforcement="advisory">
+  <check condition="has_assumptions">
+    There are untested assumptions worth validating (APIs, data sources, UX patterns, integrations)
+  </check>
+  <check condition="not_trivial">
+    The assumptions are non-trivial enough that a prototype adds value over just reading docs
+  </check>
+  <check condition="scope_bounded">
+    The prototype can be completed in under one day
+  </check>
+</preconditions>
+
+## What It Creates
+
+**Durable output:**
+- `docs/prototypes/<topic-slug>-validation-<date>.md` — Validation report
+
+**Temporary output (deleted after report):**
+- `prototypes/<topic-slug>/` — Throwaway prototype code
+
+## Success Output
+
+```
+Prototype complete
+
+Validation Goals:
+  [proved]       Stripe webhook payload includes refund metadata fields
+  [proved]       Webhook delivery latency is under 2s for test events
+  [disproved]    Free tier webhook rate limit is sufficient for peak traffic
+  [inconclusive] Retry logic handles partial failures gracefully
+
+Surprises:
+  - Webhook signature verification requires raw body access — framework middleware may parse it first
+
+Constraints Discovered:
+  - Free tier: 500 webhooks/hour (need queuing strategy or paid tier for peak)
+  - Refund metadata format changed in Stripe API v2024-12 — must pin version
+
+Report written:
+  docs/prototypes/stripe-refund-webhooks-validation-2026-04-04.md
+
+Prototype cleaned up:
+  prototypes/stripe-refund-webhooks/ [deleted]
+
+What's next?
+1. Proceed to /ce:plan with validated constraints
+2. Run another prototype round (for inconclusive goals)
+3. Revisit requirements with /ce:brainstorm (for disproved goals)
+4. Update existing requirements document with findings
+5. Other
+```
+
+Present the "What's next?" options using the platform's blocking question tool.
+
+## Common Mistakes to Avoid
+
+| Wrong | Correct |
+|-------|---------|
+| Mocking or stubbing the external system being validated | Connect to the real service — the prototype exists to test it |
+| Building for a full day with no clear validation goals | Define goals first; if scope exceeds one day, move to `/ce:plan` |
+| Applying project code standards (linting, tests, architecture) | Speed is the only standard — throwaway code has no quality bar |
+| Recording a validation result without user feedback on subjective goals | Present the prototype and wait for the user to test it before marking proved/disproved |
+| Keeping the prototype directory after the report is written | Delete the prototype; the validation report is the durable artifact |
+| Skipping the effort alignment conversation | Classify scope (Lightweight/Standard/Deep) and confirm with the user before building |
+
+## Related Commands
+
+- `/ce:brainstorm` — Defines WHAT to build (upstream)
+- `/ce:plan` — Defines HOW to build it (downstream, consumes validation report)
+- `/ce:work` — Executes the plan
+- `/ce:compound` — Documents solved problems (different lifecycle)
diff --git a/plugins/compound-engineering/skills/ce-prototype/assets/validation-report-template.md b/plugins/compound-engineering/skills/ce-prototype/assets/validation-report-template.md
new file mode 100644
index 000000000..1f98b7d9f
--- /dev/null
+++ b/plugins/compound-engineering/skills/ce-prototype/assets/validation-report-template.md
@@ -0,0 +1,72 @@
+# Validation Report Template
+
+Use this template when writing prototype validation reports to `docs/prototypes/`.
+
+```markdown
+---
+title: [Topic] Prototype Validation
+date: YYYY-MM-DD
+topic: <kebab-case-topic>
+origin: <path to requirements doc, if any>
+status: complete | partial
+goals_proved: <count>
+goals_disproved: <count>
+goals_inconclusive: <count>
+tags: [prototype, validation, keyword-one, keyword-two]
+---
+
+# [Topic] Prototype Validation
+
+## Summary
+
+[2-3 sentence summary: what was prototyped, why, and the headline result]
+
+## Origin
+
+**Requirements document:** [path or "none — prototyped from direct description"]
+**Prototype trigger:** [What prompted this prototype — untested assumption, user request, brainstorm recommendation]
+
+## Validation Goals and Results
+
+### Goal 1: [Specific goal statement]
+- **Status:** Proved / Disproved / Inconclusive
+- **Evidence:** [What was observed — API responses, screenshots, measurements, user feedback]
+- **Detail:** [Deeper explanation if needed]
+
+### Goal 2: [Specific goal statement]
+- **Status:** Proved / Disproved / Inconclusive
+- **Evidence:** [What was observed]
+- **Detail:** [Deeper explanation if needed]
+
+[Repeat for each goal]
+
+## Surprises
+
+[Unexpected discoveries that affect planning — things that were not validation goals but emerged during prototyping. Omit this section if there were no surprises.]
+
+- [Surprise 1 and its implication]
+- [Surprise 2 and its implication]
+
+## Constraints Discovered
+
+[Hard constraints that the plan must account for. Omit if none discovered.]
+
+| Constraint | Impact | Mitigation |
+|-----------|--------|------------|
+| [e.g., API rate limit: 25k/month] | [e.g., Exceeds free tier for MVP traffic] | [e.g., Implement caching or upgrade to paid tier] |
+
+## Recommendations
+
+[Based on the results, what should happen next]
+
+- **For planning:** [Constraints and validated assumptions that /ce:plan should incorporate]
+- **For requirements:** [Any requirements that need revision based on disproved goals]
+- **For further prototyping:** [Goals that need another round, if any]
+
+## Prototype Details
+
+**Tech used:** [e.g., Static HTML + fetch API, Python script, curl commands]
+**Time spent:** [Actual effort, e.g., "~25 minutes"]
+**Prototype location:** [Deleted / Preserved at <path>]
+**Artifacts preserved:** [List any files moved out of prototype before deletion, or "none"]
+```
diff --git a/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
new file mode 100644
index 000000000..e3ef7f1d7
--- /dev/null
+++ b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
@@ -0,0 +1,59 @@
+# Validation Report Schema
+
+Canonical frontmatter fields for prototype validation reports in `docs/prototypes/`.
+
+## Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | Descriptive title: "[Topic] Prototype Validation" |
+| `date` | string (YYYY-MM-DD) | Date the validation was completed |
+| `topic` | string (kebab-case) | Topic slug matching the prototype directory name |
+| `status` | enum: `complete`, `partial` | Whether all validation goals were tested |
+| `goals_proved` | integer | Count of goals with "Proved" status |
+| `goals_disproved` | integer | Count of goals with "Disproved" status |
+| `goals_inconclusive` | integer | Count of goals with "Inconclusive" status |
+
+## Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `origin` | string (repo-relative path) | Path to the upstream requirements document, if any |
+| `tags` | array[string] | Search keywords, lowercase and hyphen-separated. Always include `prototype` and `validation`. Max 8 tags. |
+| `prototype_preserved` | boolean | Whether the prototype code was kept (default: false) |
+| `prototype_path` | string | Path to preserved prototype, if `prototype_preserved: true` |
+| `effort_minutes` | integer | Approximate time spent on the prototype |
+
+## Validation Goal Statuses
+
+| Status | Meaning | Planning Impact |
+|--------|---------|----------------|
+| **Proved** | Assumption confirmed with evidence | Proceed with confidence — incorporate as validated constraint |
+| **Disproved** | Assumption was wrong | Requirements or approach needs revision before planning |
+| **Inconclusive** | Could not determine — needs more testing or different approach | Consider a focused second prototype round, or flag as a risk in the plan |
+
+## Naming Convention
+
+File: `docs/prototypes/<topic-slug>-validation-<YYYY-MM-DD>.md`
+
+Examples:
+- `docs/prototypes/stripe-refund-webhooks-validation-2026-04-04.md`
+- `docs/prototypes/payment-api-validation-2026-03-15.md`
+- `docs/prototypes/image-recognition-validation-2026-04-01.md`
+
+## Relationship to Other Compound Artifacts
+
+```
+docs/brainstorms/*-requirements.md  (upstream — defines what to build)
+        |
+        v
+docs/prototypes/*-validation-*.md   (this — validates assumptions)
+        |
+        v
+docs/plans/*-plan.md                (downstream — references validation results)
+        |
+        v
+docs/solutions/                     (post-implementation — documents learnings)
+```
+
+The validation report is referenced by `/ce:plan` the same way `/ce:plan` references requirements documents — as an origin input that grounds planning decisions in evidence rather than assumptions.

From 8fd0915bb0e3ae79e8b3d9cc3e0f47623454cf9f Mon Sep 17 00:00:00 2001
From: Rodrigo Haertel <rodrigo.haertel@twism.com>
Date: Sat, 4 Apr 2026 17:03:32 -0300
Subject: [PATCH 2/7] fix: address PR review feedback on ce:prototype

- Move prototype scratch files from top-level prototypes/ to
  .context/compound-engineering/prototypes/ to comply with AGENTS.md
  scratch-space rule for ephemeral workflow artifacts
- Pass concise brainstorm summary to /ce:prototype when no requirements
  doc exists, avoiding unnecessary re-asking of context the user already
  provided during brainstorming

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../skills/ce-brainstorm/references/handoff.md     |  2 +-
 .../skills/ce-prototype/SKILL.md                   | 14 +++++++-------
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md b/plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md
index 5368e4f6c..4ec07c209 100644
--- a/plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md
+++ b/plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md
@@ -38,7 +38,7 @@ Immediately run `/ce:plan` in the current session. Pass the requirements documen
 
 **If user selects "Prototype first":**
 
-Immediately run `/ce:prototype` in the current session. Pass the requirements document path when one exists. The prototype skill will extract testable assumptions from the requirements, validate them, and produce a validation report that feeds into `/ce:plan`. Do not print the closing summary first.
+Immediately run `/ce:prototype` in the current session. Pass the requirements document path when one exists; otherwise pass a concise summary of the finalized brainstorm decisions so the prototype skill has context without re-asking the user. The prototype skill will extract testable assumptions, validate them, and produce a validation report that feeds into `/ce:plan`. Do not print the closing summary first.
 
 **If user selects "Proceed directly to work":**
 
diff --git a/plugins/compound-engineering/skills/ce-prototype/SKILL.md b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
index e5aa4811d..8f35c7078 100644
--- a/plugins/compound-engineering/skills/ce-prototype/SKILL.md
+++ b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
@@ -14,7 +14,7 @@ Prototyping sits between brainstorm and planning because planning without valida
 
 **This skill does not produce production code.** It produces a throwaway prototype and a durable validation report. The prototype gets deleted. The report feeds into `/ce:plan`.
 
-**IMPORTANT: All file references in generated documents must use repo-relative paths (e.g., `prototypes/stripe-refund-webhooks/`), never absolute paths.**
+**IMPORTANT: All file references in generated documents must use repo-relative paths (e.g., `.context/compound-engineering/prototypes/stripe-refund-webhooks/`), never absolute paths.**
 
 ## Core Principles
 
@@ -55,7 +55,7 @@ If no requirements document exists, proceed from the user's description directly
 
 #### 0.2 Check for Existing Prototypes
 
-Search for existing prototype directories (`prototypes/`, `docs/prototypes/`, or similar patterns in the repo). If a previous prototype for the same topic exists, ask the user whether to build on it or start fresh.
+Search for existing prototype work (`.context/compound-engineering/prototypes/`, `docs/prototypes/`, or similar patterns in the repo). If a previous prototype or validation report for the same topic exists, ask the user whether to build on it or start fresh.
 
 ### Phase 1: Define Validation Goals
 
@@ -99,10 +99,10 @@ Do not proceed until effort is aligned.
 
 #### 2.1 Create Isolated Prototype Directory
 
-Scaffold the prototype in an isolated location:
+Scaffold the prototype under the compound-engineering scratch space:
 
 ```
-prototypes/
+.context/compound-engineering/prototypes/
   <topic-slug>/
     ... prototype files ...
 ```
@@ -171,7 +171,7 @@ If anything is found, flag it to the user with a brief explanation. Let them dec
 
 #### 4.2 Clean Up
 
-Delete the prototype directory. The validation report in `docs/prototypes/` persists.
+Delete the prototype directory under `.context/compound-engineering/prototypes/`. The validation report in `docs/prototypes/` persists.
 
 If the user explicitly asks to keep the prototype, respect that — but note in the validation report that the prototype code still exists and where.
 
@@ -215,7 +215,7 @@ If this prototype was triggered manually (not from a brainstorm recommendation):
 - `docs/prototypes/<topic-slug>-validation-<date>.md` — Validation report
 
 **Temporary output (deleted after report):**
-- `prototypes/<topic-slug>/` — Throwaway prototype code
+- `.context/compound-engineering/prototypes/<topic-slug>/` — Throwaway prototype code
 
 ## Success Output
 
@@ -239,7 +239,7 @@ Report written:
   docs/prototypes/stripe-refund-webhooks-validation-2026-04-04.md
 
 Prototype cleaned up:
-  prototypes/stripe-refund-webhooks/ [deleted]
+  .context/compound-engineering/prototypes/stripe-refund-webhooks/ [deleted]
 
 What's next?
 1. Proceed to /ce:plan with validated constraints

From dfce330d96db5483be6e5309d184f3196957dcf8 Mon Sep 17 00:00:00 2001
From: Rodrigo Haertel <rodrigo.haertel@twism.com>
Date: Sat, 4 Apr 2026 23:18:21 -0300
Subject: [PATCH 3/7] fix: improve ce:prototype skill based on real-world usage
 learnings

Add repo context scan and prototyping-needed gate to Phase 0, strengthen
external data source discovery guidance (no arbitrary timebox), add
shortcut decision heuristic, set iteration expectations, and expand
common mistakes table with lessons from first real prototype session.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../skills/ce-prototype/SKILL.md              | 25 ++++++++++++++++++-
 .../references/validation-report-schema.md    |  1 +
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/plugins/compound-engineering/skills/ce-prototype/SKILL.md b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
index 8f35c7078..f16c9ad1f 100644
--- a/plugins/compound-engineering/skills/ce-prototype/SKILL.md
+++ b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
@@ -57,6 +57,23 @@ If no requirements document exists, proceed from the user's description directly
 
 Search for existing prototype work (`.context/compound-engineering/prototypes/`, `docs/prototypes/`, or similar patterns in the repo). If a previous prototype or validation report for the same topic exists, ask the user whether to build on it or start fresh.
 
+#### 0.3 Repo Context Scan
+
+Before suggesting validation goals, do a light scan of the codebase for code that already touches the domain being prototyped (existing API integrations, data models, utility functions, config patterns). This serves two purposes:
+- **Avoid redundant validation** — If the repo already has a working Stripe integration, prototyping "can we connect to Stripe?" is unnecessary. Focus validation goals on what is genuinely unknown.
+- **Inform the build** — Existing patterns, wrappers, or config conventions can speed up the prototype even though prototype code does not need to follow project standards.
+
+Keep the scan proportional to scope — a quick keyword search for Lightweight, a broader pattern scan for Standard/Deep.
+
+#### 0.4 Assess Whether Prototyping Is Needed
+
+Some assumptions can be resolved without building anything:
+- **Documentation answers it** — The API docs clearly specify the data format, rate limits, or behavior in question. Reading is cheaper than coding.
+- **Existing code answers it** — The repo already integrates with the service and the assumption can be verified by reading the existing implementation.
+- **Trivial to verify** — A single curl command or REPL session answers the question without needing a prototype scaffold.
+
+If all assumptions fall into these categories, say so and recommend skipping to `/ce:plan`. Only prototype when the assumption requires building something to test — an interaction flow, a multi-step integration, visual quality judgment, or behavior that cannot be determined from docs alone.
+
 ### Phase 1: Define Validation Goals
 
 This is the most important phase. A prototype without clear goals is aimless.
@@ -119,12 +136,16 @@ For each validation goal, build the minimum artifact that answers the question:
 - **Integration** — Connect to the real service, verify behavior
 - **Performance** — Time real operations, measure what matters
 
-**Critical rule:** Before taking a shortcut on any step, evaluate whether it compromises a validation goal. If there is any doubt, ask the user. For example:
+**External data source discovery:** When a validation goal depends on a real external source (API, CDN, dataset), invest the time needed to find and connect to the right one. Using the real integration is often the entire point of the prototype — hardcoding or faking the data source defeats the validation goal. Search docs, try endpoints, and iterate until the real data flows. Only ask the user for help if you hit an access barrier (authentication, paid tier, private API) that you cannot resolve yourself.
+
+**Shortcut decision rule:** Before taking a shortcut on any step, ask: "Does this shortcut touch the same dimension as any validation goal?" If the answer is yes, do not take the shortcut — use real data, real services, real interactions. If the answer is no, the shortcut is fine. When in doubt, ask the user. Examples:
 - Hardcoding sample data is fine if the goal is testing UX layout
 - Hardcoding sample data is NOT fine if the goal is testing data source quality
 - Using a placeholder image is fine if testing game mechanics
 - Using a placeholder image is NOT fine if testing image recognition quality
 
+**Iteration is expected:** Expect 1-3 build iterations. After each iteration, present the prototype to the user with explicit testing instructions and wait for feedback before proceeding. Broken interactions or wrong layout priorities are normal — fix before moving on. Do not treat the first build as the final build.
+
 #### 2.3 Validate Each Goal
 
 After building, test each validation goal explicitly. Many goals — especially UX viability, data quality perception, and "does this feel right?" questions — **require the user to interact with the prototype and provide feedback**. Automated checks alone cannot answer whether an image source looks good enough or whether a game mechanic feels fun.
@@ -261,6 +282,8 @@ Present the "What's next?" options using the platform's blocking question tool.
 | Recording a validation result without user feedback on subjective goals | Present the prototype and wait for the user to test it before marking proved/disproved |
 | Keeping the prototype directory after the report is written | Delete the prototype; the validation report is the durable artifact |
 | Skipping the effort alignment conversation | Classify scope (Lightweight/Standard/Deep) and confirm with the user before building |
+| Giving up on finding the right external API and using a fake or placeholder instead | Invest the time to find and connect to the real data source — that is what the prototype exists to validate |
+| Prototyping something that could be answered by reading docs or existing code | Scan the repo and API docs first; only prototype what genuinely requires building to test |
 
 ## Related Commands
 
diff --git a/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
index e3ef7f1d7..b8658ea9b 100644
--- a/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
+++ b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
@@ -23,6 +23,7 @@ Canonical frontmatter fields for prototype validation reports in `docs/prototype
 | `prototype_preserved` | boolean | Whether the prototype code was kept (default: false) |
 | `prototype_path` | string | Path to preserved prototype, if `prototype_preserved: true` |
 | `effort_minutes` | integer | Approximate time spent on the prototype |
+| `iterations` | integer | Number of build-feedback iterations before final validation (typically 1-3) |
 
 ## Validation Goal Statuses
 

From d8497bd02ebba56d64e6f23983aa474e249160e2 Mon Sep 17 00:00:00 2001
From: Rodrigo Haertel <rodrigo.haertel@twism.com>
Date: Sat, 4 Apr 2026 23:39:26 -0300
Subject: [PATCH 4/7] fix: address 3 unresolved PR review comments on
 ce:prototype

- Use per-run scratch directories (.context/compound-engineering/ce-prototype/<topic>-<timestamp>/)
  to avoid collisions between concurrent sessions (AGENTS.md scratch space rule)
- Append sequence number to validation report filename when same-day
  report already exists, preventing overwrites on second prototype rounds
- Pass validation report path in handoff to /ce:plan so planning has
  direct access to validated constraints without relying on context window

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../skills/ce-prototype/SKILL.md              | 24 ++++++++++---------
 .../references/validation-report-schema.md    |  3 +++
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/plugins/compound-engineering/skills/ce-prototype/SKILL.md b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
index f16c9ad1f..9b138942b 100644
--- a/plugins/compound-engineering/skills/ce-prototype/SKILL.md
+++ b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
@@ -14,7 +14,7 @@ Prototyping sits between brainstorm and planning because planning without valida
 
 **This skill does not produce production code.** It produces a throwaway prototype and a durable validation report. The prototype gets deleted. The report feeds into `/ce:plan`.
 
-**IMPORTANT: All file references in generated documents must use repo-relative paths (e.g., `.context/compound-engineering/prototypes/stripe-refund-webhooks/`), never absolute paths.**
+**IMPORTANT: All file references in generated documents must use repo-relative paths (e.g., `.context/compound-engineering/ce-prototype/stripe-refund-webhooks-20260404-143022/`), never absolute paths.**
 
 ## Core Principles
 
@@ -55,7 +55,7 @@ If no requirements document exists, proceed from the user's description directly
 
 #### 0.2 Check for Existing Prototypes
 
-Search for existing prototype work (`.context/compound-engineering/prototypes/`, `docs/prototypes/`, or similar patterns in the repo). If a previous prototype or validation report for the same topic exists, ask the user whether to build on it or start fresh.
+Search for existing prototype work (`.context/compound-engineering/ce-prototype/`, `docs/prototypes/`, or similar patterns in the repo). If a previous prototype or validation report for the same topic exists, ask the user whether to build on it or start fresh.
 
 #### 0.3 Repo Context Scan
 
@@ -116,11 +116,11 @@ Do not proceed until effort is aligned.
 
 #### 2.1 Create Isolated Prototype Directory
 
-Scaffold the prototype under the compound-engineering scratch space:
+Scaffold the prototype under the compound-engineering scratch space with a per-run subdirectory to avoid collisions between concurrent sessions or repeated runs on the same topic:
 
 ```
-.context/compound-engineering/prototypes/
-  <topic-slug>/
+.context/compound-engineering/ce-prototype/
+  <topic-slug>-<YYYYMMDD-HHMMSS>/
     ... prototype files ...
 ```
 
@@ -171,7 +171,7 @@ For each goal, record:
 
 Read `assets/validation-report-template.md` for the report structure.
 
-Write the report to `docs/prototypes/<topic-slug>-validation-<date>.md`.
+Write the report to `docs/prototypes/<topic-slug>-validation-<date>.md`. If a report with the same name already exists (e.g., a second prototype round on the same day), append a sequence number: `<topic-slug>-validation-<date>-002.md`.
 
 Create `docs/prototypes/` if it does not exist.
 
@@ -192,7 +192,7 @@ If anything is found, flag it to the user with a brief explanation. Let them dec
 
 #### 4.2 Clean Up
 
-Delete the prototype directory under `.context/compound-engineering/prototypes/`. The validation report in `docs/prototypes/` persists.
+Delete the prototype directory under `.context/compound-engineering/ce-prototype/`. The validation report in `docs/prototypes/` persists.
 
 If the user explicitly asks to keep the prototype, respect that — but note in the validation report that the prototype code still exists and where.
 
@@ -202,13 +202,15 @@ Based on the validation results, recommend the appropriate next step:
 
 | Result | Recommendation |
 |--------|---------------|
-| All goals proved | Proceed to `/ce:plan` — validated constraints feed directly into planning |
+| All goals proved | Proceed to `/ce:plan` — pass the validation report path so planning can reference validated constraints |
 | Some goals disproved | Revisit requirements with `/ce:brainstorm` — scope or approach may need to change |
 | Inconclusive goals | Run a focused second prototype round on the inconclusive goals |
 | Major surprise discovered | Discuss implications before proceeding — the discovery may reshape the entire approach |
 
 Present as a question using the platform's blocking question tool.
 
+**Handoff to /ce:plan:** When the user selects planning, run `/ce:plan` and pass the validation report path (e.g., `/ce:plan docs/prototypes/<topic-slug>-validation-<date>.md`). If a requirements document also exists, pass both paths. This ensures the plan has direct access to validated constraints and discovered surprises without relying on context window or user re-entry.
+
 ### Phase 5 (Optional): Brainstorm Integration Suggestion
 
 If this prototype was triggered manually (not from a brainstorm recommendation):
@@ -236,7 +238,7 @@ If this prototype was triggered manually (not from a brainstorm recommendation):
 - `docs/prototypes/<topic-slug>-validation-<date>.md` — Validation report
 
 **Temporary output (deleted after report):**
-- `.context/compound-engineering/prototypes/<topic-slug>/` — Throwaway prototype code
+- `.context/compound-engineering/ce-prototype/<topic-slug>-<YYYYMMDD-HHMMSS>/` — Throwaway prototype code
 
 ## Success Output
 
@@ -260,10 +262,10 @@ Report written:
   docs/prototypes/stripe-refund-webhooks-validation-2026-04-04.md
 
 Prototype cleaned up:
-  .context/compound-engineering/prototypes/stripe-refund-webhooks/ [deleted]
+  .context/compound-engineering/ce-prototype/stripe-refund-webhooks-20260404-143022/ [deleted]
 
 What's next?
-1. Proceed to /ce:plan with validated constraints
+1. Proceed to /ce:plan docs/prototypes/stripe-refund-webhooks-validation-2026-04-04.md
 2. Run another prototype round (for inconclusive goals)
 3. Revisit requirements with /ce:brainstorm (for disproved goals)
 4. Update existing requirements document with findings
diff --git a/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
index b8658ea9b..7bafe27e0 100644
--- a/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
+++ b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
@@ -37,8 +37,11 @@ Canonical frontmatter fields for prototype validation reports in `docs/prototype
 
 File: `docs/prototypes/<topic-slug>-validation-<YYYY-MM-DD>.md`
 
+If a report with the same name already exists (e.g., a second prototype round on the same day), append a sequence number: `<topic-slug>-validation-<YYYY-MM-DD>-002.md`.
+
 Examples:
 - `docs/prototypes/stripe-refund-webhooks-validation-2026-04-04.md`
+- `docs/prototypes/stripe-refund-webhooks-validation-2026-04-04-002.md` (second round, same day)
 - `docs/prototypes/payment-api-validation-2026-03-15.md`
 - `docs/prototypes/image-recognition-validation-2026-04-01.md`
 

From 1e929135164a9cd8670451a50bd8253f4ad33d60 Mon Sep 17 00:00:00 2001
From: Rodrigo Haertel <rodrigo.haertel@twism.com>
Date: Sat, 4 Apr 2026 23:48:57 -0300
Subject: [PATCH 5/7] fix: apply skill-reviewer feedback and preserve prototype
 to durable path

- Move preserved prototypes from .context/ to prototypes/<topic>/ at
  repo root since .context/ is ephemeral scratch space
- Add trigger phrases: 'feasibility check', 'experiment with this',
  'will this actually work'
- Mark origin field as optional in template to match schema
- Add example validation report in examples/ for LLM quality reference
- Update prototype_path description in schema

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../skills/ce-prototype/SKILL.md              |  6 +-
 .../assets/validation-report-template.md      |  4 +-
 .../stripe-refund-webhooks-validation.md      | 73 +++++++++++++++++++
 .../references/validation-report-schema.md    |  2 +-
 4 files changed, 79 insertions(+), 6 deletions(-)
 create mode 100644 plugins/compound-engineering/skills/ce-prototype/examples/stripe-refund-webhooks-validation.md

diff --git a/plugins/compound-engineering/skills/ce-prototype/SKILL.md b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
index 9b138942b..89cb63347 100644
--- a/plugins/compound-engineering/skills/ce-prototype/SKILL.md
+++ b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce:prototype
-description: "Build a throwaway prototype to validate assumptions before committing to an implementation plan. Use when the user says 'prototype this', 'let me test this idea first', 'spike on this', 'validate this before planning', 'build a quick prototype', 'I want to test if this works', 'try this out before we plan', 'proof of concept', 'quick test', 'throwaway prototype', or 'validate assumptions'. Also use when a brainstorm or requirements document contains untested assumptions about APIs, data sources, UX patterns, or integrations, or when the user wants to de-risk before planning."
+description: "Build a throwaway prototype to validate assumptions before committing to an implementation plan. Use when the user says 'prototype this', 'let me test this idea first', 'spike on this', 'validate this before planning', 'build a quick prototype', 'I want to test if this works', 'try this out before we plan', 'proof of concept', 'quick test', 'throwaway prototype', 'validate assumptions', 'feasibility check', 'experiment with this', or 'will this actually work'. Also use when a brainstorm or requirements document contains untested assumptions about APIs, data sources, UX patterns, or integrations, or when the user wants to de-risk before planning."
 argument-hint: "[optional: feature description, requirements doc path, or specific assumptions to validate]"
 ---
 
@@ -194,7 +194,7 @@ If anything is found, flag it to the user with a brief explanation. Let them dec
 
 Delete the prototype directory under `.context/compound-engineering/ce-prototype/`. The validation report in `docs/prototypes/` persists.
 
-If the user explicitly asks to keep the prototype, respect that — but note in the validation report that the prototype code still exists and where.
+If the user explicitly asks to keep the prototype, move it out of `.context/` (which is ephemeral scratch space subject to cleanup) to a durable location: `prototypes/<topic-slug>/` at the repo root. Note the preserved path in the validation report.
 
 #### 4.3 Recommend Next Step
 
@@ -238,7 +238,7 @@ If this prototype was triggered manually (not from a brainstorm recommendation):
 - `docs/prototypes/<topic-slug>-validation-<date>.md` — Validation report
 
 **Temporary output (deleted after report):**
-- `.context/compound-engineering/ce-prototype/<topic-slug>-<YYYYMMDD-HHMMSS>/` — Throwaway prototype code
+- `.context/compound-engineering/ce-prototype/<topic-slug>-<YYYYMMDD-HHMMSS>/` — Throwaway prototype code (moved to `prototypes/<topic-slug>/` if user chooses to keep it)
 
 ## Success Output
 
diff --git a/plugins/compound-engineering/skills/ce-prototype/assets/validation-report-template.md b/plugins/compound-engineering/skills/ce-prototype/assets/validation-report-template.md
index 1f98b7d9f..c83ec5743 100644
--- a/plugins/compound-engineering/skills/ce-prototype/assets/validation-report-template.md
+++ b/plugins/compound-engineering/skills/ce-prototype/assets/validation-report-template.md
@@ -7,7 +7,7 @@ Use this template when writing prototype validation reports to `docs/prototypes/
 title: [Topic] Prototype Validation
 date: YYYY-MM-DD
 topic: <kebab-case-topic>
-origin: <path to requirements doc, if any>
+origin: <path to requirements doc, if any> # optional
 status: complete | partial
 goals_proved: <count>
 goals_disproved: <count>
@@ -67,6 +67,6 @@ tags: [prototype, validation, keyword-one, keyword-two]
 
 **Tech used:** [e.g., Static HTML + fetch API, Python script, curl commands]
 **Time spent:** [Actual effort, e.g., "~25 minutes"]
-**Prototype location:** [Deleted / Preserved at <path>]
+**Prototype location:** [Deleted / Preserved at prototypes/<topic-slug>/]
 **Artifacts preserved:** [List any files moved out of prototype before deletion, or "none"]
 ```
diff --git a/plugins/compound-engineering/skills/ce-prototype/examples/stripe-refund-webhooks-validation.md b/plugins/compound-engineering/skills/ce-prototype/examples/stripe-refund-webhooks-validation.md
new file mode 100644
index 000000000..3d2cc10e8
--- /dev/null
+++ b/plugins/compound-engineering/skills/ce-prototype/examples/stripe-refund-webhooks-validation.md
@@ -0,0 +1,73 @@
+---
+title: Stripe Refund Webhooks Prototype Validation
+date: 2026-04-04
+topic: stripe-refund-webhooks
+origin: docs/brainstorms/2026-04-01-stripe-refund-webhooks-requirements.md
+status: complete
+goals_proved: 2
+goals_disproved: 1
+goals_inconclusive: 1
+tags: [prototype, validation, stripe, webhooks, refunds]
+effort_minutes: 30
+iterations: 2
+---
+
+# Stripe Refund Webhooks Prototype Validation
+
+## Summary
+
+Prototyped Stripe webhook handling for refund events to validate payload structure, delivery latency, and rate limit viability before planning the refund notification system. Payload and latency validated well; free tier rate limits are insufficient for peak traffic.
+
+## Origin
+
+**Requirements document:** `docs/brainstorms/2026-04-01-stripe-refund-webhooks-requirements.md`
+**Prototype trigger:** Requirements assumed webhook payload includes refund metadata -- needed verification against real API behavior.
+
+## Validation Goals and Results
+
+### Goal 1: Stripe webhook payload includes refund metadata fields
+
+- **Status:** Proved
+- **Evidence:** Triggered test refund events via Stripe CLI. The `charge.refund.updated` event payload includes `reason`, `receipt_number`, `amount`, `currency`, and `metadata` object. All fields needed for the notification system are present.
+- **Detail:** Metadata is nested under `data.object.metadata`, not at the top level. The plan should reference this path explicitly.
+
+### Goal 2: Webhook delivery latency is under 2s for test events
+
+- **Status:** Proved
+- **Evidence:** Measured 50 test webhook deliveries. Mean latency: 340ms. P95: 890ms. Max: 1.4s. All within the 2s threshold.
+
+### Goal 3: Free tier webhook rate limit is sufficient for peak traffic
+
+- **Status:** Disproved
+- **Evidence:** Free tier allows 500 webhooks/hour. Peak traffic estimate from requirements: 1,200 refund events/hour during holiday sales. Free tier covers ~42% of peak demand.
+- **Detail:** Paid tier ($0.01/event beyond free tier) or a queuing strategy needed. Estimated monthly cost at peak: ~$168.
+
+### Goal 4: Retry logic handles partial failures gracefully
+
+- **Status:** Inconclusive
+- **Evidence:** Stripe retries failed deliveries up to 3 times with exponential backoff. Simulated partial failures (returning 500 on first attempt, 200 on retry) worked correctly. However, the test only covered single-event retries -- behavior under concurrent retry storms during an outage recovery was not tested.
+
+## Surprises
+
+- Webhook signature verification requires access to the raw request body. Express middleware that parses JSON before signature verification will break it. The implementation must use `express.raw()` on the webhook endpoint.
+
+## Constraints Discovered
+
+| Constraint | Impact | Mitigation |
+|-----------|--------|------------|
+| Free tier: 500 webhooks/hour | Insufficient for peak traffic (1,200/hr) | Implement queuing strategy or upgrade to paid tier |
+| Refund metadata format changed in Stripe API v2024-12 | Field paths differ between API versions | Pin API version in webhook endpoint configuration |
+| Signature verification needs raw body | Standard JSON parsing middleware breaks verification | Use `express.raw()` middleware on webhook route |
+
+## Recommendations
+
+- **For planning:** Pin Stripe API version, use `express.raw()` on webhook endpoint, implement a queue for peak traffic buffering.
+- **For requirements:** Update rate limit assumption -- free tier is insufficient. Decision needed: paid tier vs. queuing.
+- **For further prototyping:** Retry behavior under concurrent storm conditions (Goal 4) should be validated once the queue architecture is designed.
+
+## Prototype Details
+
+**Tech used:** Node.js script, Stripe CLI for webhook forwarding, manual event triggers
+**Time spent:** ~30 minutes
+**Prototype location:** Deleted
+**Artifacts preserved:** None
diff --git a/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
index 7bafe27e0..8d5e6e1fe 100644
--- a/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
+++ b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
@@ -21,7 +21,7 @@ Canonical frontmatter fields for prototype validation reports in `docs/prototype
 | `origin` | string (repo-relative path) | Path to the upstream requirements document, if any |
 | `tags` | array[string] | Search keywords, lowercase and hyphen-separated. Always include `prototype` and `validation`. Max 8 tags. |
 | `prototype_preserved` | boolean | Whether the prototype code was kept (default: false) |
-| `prototype_path` | string | Path to preserved prototype, if `prototype_preserved: true` |
+| `prototype_path` | string | Path to preserved prototype (e.g., `prototypes/<topic-slug>/`), if `prototype_preserved: true` |
 | `effort_minutes` | integer | Approximate time spent on the prototype |
 | `iterations` | integer | Number of build-feedback iterations before final validation (typically 1-3) |
 

From 8514d073565106fa8c994483811d32e03bd112ff Mon Sep 17 00:00:00 2001
From: Rodrigo Haertel <rodrigo.haertel@twism.com>
Date: Sun, 5 Apr 2026 00:15:57 -0300
Subject: [PATCH 6/7] fix: address 4 unresolved PR review comments (round 2)

- Fix report sequence to use next available number (-002, -003, etc.)
  instead of hardcoded -002
- Use timestamped path when preserving prototype and directory already
  exists to prevent overwriting earlier preserved work
- Pass constraints summary in handoff to /ce:plan since plan skill
  does not auto-discover validation reports
- Add ce:prototype to README workflow table

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 plugins/compound-engineering/README.md                      | 1 +
 plugins/compound-engineering/skills/ce-prototype/SKILL.md   | 6 +++---
 .../ce-prototype/references/validation-report-schema.md     | 2 +-
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md
index f783bcc06..4c2281fa2 100644
--- a/plugins/compound-engineering/README.md
+++ b/plugins/compound-engineering/README.md
@@ -19,6 +19,7 @@ The primary entry points for engineering work, invoked as slash commands:
 |-------|-------------|
 | `/ce:ideate` | Discover high-impact project improvements through divergent ideation and adversarial filtering |
 | `/ce:brainstorm` | Explore requirements and approaches before planning |
+| `/ce:prototype` | Build throwaway prototypes to validate assumptions before planning |
 | `/ce:plan` | Create structured plans for any multi-step task -- software features, research workflows, events, study plans -- with automatic confidence checking |
 | `/ce:review` | Structured code review with tiered persona agents, confidence gating, and dedup pipeline |
 | `/ce:work` | Execute work items systematically |
diff --git a/plugins/compound-engineering/skills/ce-prototype/SKILL.md b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
index 89cb63347..69c0f9d1c 100644
--- a/plugins/compound-engineering/skills/ce-prototype/SKILL.md
+++ b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
@@ -171,7 +171,7 @@ For each goal, record:
 
 Read `assets/validation-report-template.md` for the report structure.
 
-Write the report to `docs/prototypes/<topic-slug>-validation-<date>.md`. If a report with the same name already exists (e.g., a second prototype round on the same day), append a sequence number: `<topic-slug>-validation-<date>-002.md`.
+Write the report to `docs/prototypes/<topic-slug>-validation-<date>.md`. If a report with the same name already exists (e.g., multiple prototype rounds on the same day), append the next available sequence number: `-002`, `-003`, etc.
 
 Create `docs/prototypes/` if it does not exist.
 
@@ -194,7 +194,7 @@ If anything is found, flag it to the user with a brief explanation. Let them dec
 
 Delete the prototype directory under `.context/compound-engineering/ce-prototype/`. The validation report in `docs/prototypes/` persists.
 
-If the user explicitly asks to keep the prototype, move it out of `.context/` (which is ephemeral scratch space subject to cleanup) to a durable location: `prototypes/<topic-slug>/` at the repo root. Note the preserved path in the validation report.
+If the user explicitly asks to keep the prototype, move it out of `.context/` (which is ephemeral scratch space subject to cleanup) to a durable location at the repo root: `prototypes/<topic-slug>/`. If that directory already exists (from a prior preserved prototype), use a timestamped path (`prototypes/<topic-slug>-<YYYYMMDD-HHMMSS>/`) to avoid overwriting earlier work. Note the preserved path in the validation report.
 
 #### 4.3 Recommend Next Step
 
@@ -209,7 +209,7 @@ Based on the validation results, recommend the appropriate next step:
 
 Present as a question using the platform's blocking question tool.
 
-**Handoff to /ce:plan:** When the user selects planning, run `/ce:plan` and pass the validation report path (e.g., `/ce:plan docs/prototypes/<topic-slug>-validation-<date>.md`). If a requirements document also exists, pass both paths. This ensures the plan has direct access to validated constraints and discovered surprises without relying on context window or user re-entry.
+**Handoff to /ce:plan:** When the user selects planning, run `/ce:plan` and pass both the requirements document path (if one exists) and a concise constraints summary extracted from the validation report. The summary should include: proved/disproved goal results, key constraints discovered, and the validation report path for reference. Example: `/ce:plan docs/brainstorms/2026-04-01-topic-requirements.md — Prototype validated: [goals summary]. Constraints: [key constraints]. Full report: docs/prototypes/topic-validation-2026-04-04.md`. This ensures planning starts from validated assumptions even if `/ce:plan` does not auto-discover validation reports.
 
 ### Phase 5 (Optional): Brainstorm Integration Suggestion
 
diff --git a/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
index 8d5e6e1fe..c3a3c22d7 100644
--- a/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
+++ b/plugins/compound-engineering/skills/ce-prototype/references/validation-report-schema.md
@@ -37,7 +37,7 @@ Canonical frontmatter fields for prototype validation reports in `docs/prototype
 
 File: `docs/prototypes/<topic-slug>-validation-<YYYY-MM-DD>.md`
 
-If a report with the same name already exists (e.g., a second prototype round on the same day), append a sequence number: `<topic-slug>-validation-<YYYY-MM-DD>-002.md`.
+If a report with the same name already exists (e.g., multiple prototype rounds on the same day), append the next available sequence number: `-002`, `-003`, etc.
 
 Examples:
 - `docs/prototypes/stripe-refund-webhooks-validation-2026-04-04.md`

From 9ff17b8cd52c6468c622a7ed3610aae58d6ab5b5 Mon Sep 17 00:00:00 2001
From: Rodrigo Haertel <rodrigo.haertel@twism.com>
Date: Sun, 5 Apr 2026 00:28:44 -0300
Subject: [PATCH 7/7] fix: inline validation report template and schema with @
 inclusion

Small structural files (<150 lines) that the skill cannot function
without should use @ inclusion per AGENTS.md skill compliance checklist,
ensuring the model always has the report contract in context.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 plugins/compound-engineering/skills/ce-prototype/SKILL.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/plugins/compound-engineering/skills/ce-prototype/SKILL.md b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
index 69c0f9d1c..f3c03478f 100644
--- a/plugins/compound-engineering/skills/ce-prototype/SKILL.md
+++ b/plugins/compound-engineering/skills/ce-prototype/SKILL.md
@@ -169,7 +169,7 @@ For each goal, record:
 
 ### Phase 3: Write Validation Report
 
-Read `assets/validation-report-template.md` for the report structure.
+Use the template and schema below to write the validation report.
 
 Write the report to `docs/prototypes/<topic-slug>-validation-<date>.md`. If a report with the same name already exists (e.g., multiple prototype rounds on the same day), append the next available sequence number: `-002`, `-003`, etc.
 
@@ -177,7 +177,9 @@ Create `docs/prototypes/` if it does not exist.
 
 The validation report is the durable output — it survives after the prototype code is deleted. It must contain enough detail that `/ce:plan` (or a future reader) can understand what was tested and what was learned without access to the prototype code.
 
-For detailed field descriptions and frontmatter schema, see `references/validation-report-schema.md`.
+@./assets/validation-report-template.md
+
+@./references/validation-report-schema.md
 
 ### Phase 4: Clean Up and Recommend