AGENT SKILL

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
所属仓库
girishmotwani/atom
最近更新
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:

  1. poc-discipline.md — the authority for this skill
  2. anti-rationalization.md
  3. verification.md
  4. 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.md complete, with verbatim evidence and explicit non-coverage
  • [ ] findings.md updated during the work
  • [ ] Any skipped phase POC justified in decisions.md with 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