POCDD — Create
Bootstrap one self-contained POC file from a SOURCE. First read
../shared/conventions.md.
Configured languages for this install: python,md
Inputs
SOURCE is anything that defines the goal: a one-line sentence, an issue id/link,
a path to a document, or a provider URL. (/poc create <SOURCE> and bare
/poc <SOURCE> both arrive here.)
Procedure
- Gather context from the SOURCE. Read the file, fetch the URL, or read the
issue. Distil it into a single Goal statement. If the source is just a
sentence, use it verbatim as the goal.
- Choose the format by risk (see conventions):
- Unknown external/runtime behavior (API, OAuth, sync, time zones) →
runnable file from the templates that match this install:
- Internal/domain complexity (refactor, wiring, product rules) →
.md
when available in this install.
- When in doubt, prefer the runnable form if there is any external system to
probe; otherwise
.md.
- Name it by domain — short
kebab/snake name (e.g. calendar,
holidays-sync). Never test.
- Resolve and create
.pocs/ via ../shared/context.sh
(pocdd_ensure_dir).
- Write the file from the chosen template into
.pocs/<name>.<ext>, filling
the Goal section and setting the header phase: spike.
- Seed Remaining gaps — the highest-value step. Enumerate what must be
proven, decided, or handled to reach the goal. Tag each
[agent] or
[user], give stable ids G1…. Always run the failure-mode sweep for
anything external (auth/token refresh, pagination, rate limits, partial
failures, retries/idempotency, malformed data, time zones).
- Report: the file path, format chosen (and why), and the seeded gap list
split by owner. Suggest
/poc work <name> next (at most 2
[agent] gaps close per work pass on this install).
Guardrails
- Never write outside
.pocs/. Never commit .pocs/.
- Reference codebase by path; do not paste production code into the file.
- Do not invent product decisions — log them as
[user] gaps.
1---2name: pocdd-create3description: Create a new POC-driven feature file under .pocs/ from any source (a sentence, an issue, a document, a URL). Picks the file format by risk, writes the Goal, and seeds Remaining gaps including a failure-mode sweep. Use for "/poc <SOURCE>" or "start a POC for X".4---56# POCDD — Create78Bootstrap one self-contained POC file from a **SOURCE**. First read9[`../shared/conventions.md`](../shared/conventions.md).1011Configured languages for this install: **python,md**1213## Inputs1415`SOURCE` is anything that defines the goal: a one-line sentence, an issue id/link,16a path to a document, or a provider URL. (`/poc create <SOURCE>` and bare17`/poc <SOURCE>` both arrive here.)1819## Procedure20211. **Gather context from the SOURCE.** Read the file, fetch the URL, or read the22 issue. Distil it into a single **Goal** statement. If the source is just a23 sentence, use it verbatim as the goal.242. **Choose the format by risk** (see conventions):25 - *Unknown external/runtime behavior* (API, OAuth, sync, time zones) →26 **runnable** file from the templates that match this install:27 - Python: copy [`../templates/poc.py`](../templates/poc.py)28 - Markdown: copy [`../templates/poc.md`](../templates/poc.md)29 - *Internal/domain complexity* (refactor, wiring, product rules) → **`.md`**30 when available in this install.31 - When in doubt, prefer the runnable form if there is *any* external system to32 probe; otherwise `.md`.333. **Name it by domain** — short `kebab`/`snake` name (e.g. `calendar`,34 `holidays-sync`). Never `test`.354. **Resolve and create `.pocs/`** via [`../shared/context.sh`](../shared/context.sh)36 (`pocdd_ensure_dir`).375. **Write the file** from the chosen template into `.pocs/<name>.<ext>`, filling38 the **Goal** section and setting the header `phase: spike`.396. **Seed Remaining gaps — the highest-value step.** Enumerate what must be40 *proven*, *decided*, or *handled* to reach the goal. Tag each `[agent]` or41 `[user]`, give stable ids `G1…`. **Always run the failure-mode sweep** for42 anything external (auth/token refresh, pagination, rate limits, partial43 failures, retries/idempotency, malformed data, time zones).447. **Report**: the file path, format chosen (and why), and the seeded gap list45 split by owner. Suggest `/poc work <name>` next (at most **2**46 `[agent]` gaps close per work pass on this install).4748## Guardrails4950- Never write outside `.pocs/`. Never commit `.pocs/`.51- Reference codebase by path; do not paste production code into the file.52- Do not invent product decisions — log them as `[user]` gaps.