poc
Build, run and evaluate a throwaway Go spike that answers one falsifiable question. Produces a POC Report with verbatim evidence. Keywords: POC, proof of concept, spike, prototype, prove it, experiment, try it out.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- poc
- description
- Build, run and evaluate a throwaway Go spike that answers one falsifiable question. Produces a POC Report with verbatim evidence. Keywords: POC, proof of concept, spike, prototype, prove it, experiment, try it out.
03 SKILL.md 正文
/atom:poc
The PROVE beat. Builds a disposable Go program that answers exactly one question, runs it, and writes up what actually happened.
Used twice in the pipeline: once for the project, then once per phase that carries technical risk.
When to use
- A POC Brief exists and has been approved
- A phase in the plan has an open technical risk
- Any moment someone is about to design around an unverified assumption
Writing artifacts
Send complete POC reports, findings, decisions, and throwaway spike documentation as
UTF-8 standard input to atom-write-artifact <relative-path>. Treat any refusal or
non-zero exit as a blocker; never bypass it with a generic editor or another shell
command.
Before you start
Read, in this order:
- poc-discipline.md — the authority for this skill
- anti-rationalization.md
- verification.md
- treatment-evidence.md — required if the spike compares arms
You need an approved brief. If there isn't one, go back to /atom:discover. Building a
spike without an agreed question produces a program nobody can grade.
Step 1 — Restate the question
Copy the question out of the brief verbatim into your working notes.
Do not reword it. Rewording is how a miss becomes a hit: the question drifts toward whatever the spike turned out to be good at, and the report confirms something nobody asked.
Step 2 — Scaffold
atom poc new {slug}
Creates poc/{slug}/ with its own go.mod, a main.go stub, and a README.md
carrying the question. The spike is a separate module — it must not compile into
the production build, and it must be free to pull dependencies that production will
never take.
Step 3 — Write the spike
Write the smallest program that can answer the question.
This code is disposable, and should look it. Hardcode values. Skip error handling.
panic on anything unexpected. Put it all in main.go. Time spent making a spike
elegant is time spent on code you are about to delete.
The one thing a spike must do well is report. It should print what it found, clearly enough that the output alone settles the question:
// The spike's entire job is to answer one question, so it prints the measurement
// the question asks about — not a generic "done".
fmt.Printf("processed=%d duration=%s p99=%s\n", processed, elapsed, p99)
If you find yourself building abstractions, splitting files, or adding configuration, the question is too broad. Stop, narrow it, and check the narrowing with the developer.
The scope trap
Spikes grow. You will be tempted to also check the adjacent thing while you're in
here. Don't. A spike that answers three questions answers none of them cleanly, and
its report cannot be graded. Note the adjacent question in findings.md as a
candidate for a later spike.
Step 4 — Run it
atom poc run {slug}
Runs go vet, go build, then go run, and captures all output.
A POC that has not been executed does not exist.
Reading the spike and concluding it would work is precisely the failure this whole framework is built to prevent. If it doesn't run, it has proven nothing.
Capture the real output. You will paste it verbatim — never retyped, never rounded, never reconstructed from memory. If you lost it, run it again.
If it measures something, run it more than once. A single timing sample is noise.
Comparison spikes: prove the treatment was applied
Skip this if the spike has one arm. It is mandatory the moment the spike compares arms and intends to credit the difference to a treatment.
Work through the three checks in treatment-evidence.md before reading any result:
| # | Check | How |
|---|---|---|
| 1 | The treatment reached the model | Render each arm's prompt, compare sizes |
| 2 | Any required action actually happened | Count entries in the treatment's own usage log |
| 3 | The treated arm behaved differently at all | Compare a behavioural measure against control |
A treatment carried in the prompt arrives by construction and check 1 settles it. A treatment the agent has to do something to use — run a script, query an index, call an API — can fail silently, completing the run with no error while measuring nothing. Those treatments must log their own use.
The agent's account of what it did is not evidence. An agent that was blocked may describe the action in the past tense and produce output in the right shape for a tool it never ran.
If a check fails, the arm has proven nothing. Fix the cause, record the correction as a deviation, and rerun — do not reinterpret the numbers you already have.
Step 5 — Reach a verdict
Three outcomes. All three are successes.
| Verdict | Meaning | Next |
|---|---|---|
| Confirmed | The assumption held, and the output shows it | Proceed to /atom:spec |
| Refuted | The assumption was wrong | Back to /atom:discover with what you learned |
| Inconclusive | The spike didn't isolate the question | Sharpen and respike. Do not proceed |
Grade against the brief's success criteria, not against how you feel about the code.
Inconclusive is not a soft confirm. If the spike crashed, or the numbers came out ambiguous, or you only got it working by changing what you were testing — the verdict is Inconclusive. Writing that up as Confirmed launders a guess into the design as evidence, and every decision downstream inherits it.
Refuting your own plan is the highest-value outcome in this pipeline. You just saved the design. Report it with enthusiasm, not apology.
Step 6 — Write the POC Report
Fill in poc-report.md at
specs/{project}/poc-report.md, or specs/{project}/phase-NN-{slug}/poc-report.md
for a phase spike.
Two sections carry most of the value:
- Evidence — verbatim output, in fenced blocks.
- Explicitly Not Covered — the boundary of what this proves. A spike showing a happy path at 1k req/s is not evidence about error paths at 100k req/s, and the report must say so, or somebody will later believe it was.
Record anything that surprised you. Surprises are the highest-value content in the report — they are, by definition, the things the design would otherwise have got wrong.
Append to findings.md as you go, not from memory afterwards.
Step 7 — Gate
Present per human-gates.md: the verdict, the evidence, what it changes, and one specific question.
End your turn. Wait.
After approval
Leave the spike in poc/{slug}/. It is documentation now — the next person who
doubts the decision can re-run it.
Do not copy spike code into the implementation. It earned its shortcuts by being disposable. Production code earns its shape from the spec and the tests. Carry the knowledge forward, not the source.
Done when
- [ ] Question restated verbatim from the brief
- [ ] Spike scaffolded as its own module under
poc/{slug}/ - [ ] Spike executed, with real output captured
- [ ] For comparison spikes: treatment evidence collected for every arm before results were read
- [ ] Verdict reached against the brief's stated success criteria
- [ ]
poc-report.mdcomplete, with verbatim evidence and explicit non-coverage - [ ]
findings.mdupdated during the work - [ ] Any skipped phase POC justified in
decisions.mdwith a specific, checkable reason - [ ] Report presented at a gate and explicitly approved
Next
- Confirmed, project-level →
/atom:plan - Confirmed, phase-level →
/atom:spec - Refuted →
/atom:discover - Inconclusive → sharpen the question, respike
04 同仓库更多 Skills
tdd
Implement one phase test-first in Go: red, green, refactor, against an approved design spec. Keywords: TDD, test driven, test first, implement, red green refactor, build the phase, write the code.
spec
Write the high-level design spec for one phase, grounded in that phase POC evidence. Keywords: spec, design, design doc, architecture, API design, describe the approach.
ship
Commit, push and open a pull request for a completed phase, with the pipeline artifacts linked. Keywords: ship, PR, pull request, commit, push, open a PR, submit.
review
Standalone or phase multi-model review of a Go diff, merged into one report with severities. Keywords: review, code review, multi-model review, review my changes, review the diff, critique.
plan
Break proven work into ordered, independently shippable phases based on POC evidence. Keywords: plan, phases, break down, roadmap, decompose, milestones, sequencing.
init
Onboard a Go repository to Atom: capture its initial baseline or confirm existing setup without changes. Keywords: init, onboard, setup, install atom, bootstrap, add atom to this repo.