One useful idea
A specification states what a user needs and how you will know the system meets it. Start with a classroom operator who needs to retain a finding and its review history. “Build a good API” cannot be checked. “A stale revision returns 409 without changing the finding or audit” has a precondition, action and observable result. Write this before the integration so the implementation is not its own only judge.
Keep evidence layers separate. FFprobe observes an owned media container and duration; the API accepts supplied dimensions and frame counts. Its threshold signals are not measurements of that media. A finding stores authored classroom evidence. A distinct fixture actor exercises a review rule, not verified human identity. A successful container check does not grant rights, privacy, creative quality or publication approval.
Draw only connections that exist: owned media → quarantine and inspection; supplied metadata → API → SQLite; finding → review → current read; dependency probes → bounded process-local events. The supplied capstone does not infer dimensions from FFprobe or automatically judge a video. Name the lack of a transaction spanning HTTP, SQLite and output files: a later failure can leave earlier effects.
Reuse the Module 10 service and Module 11 helpers explicitly. Your work is the contract, integration, changed-input tests and explanation, not a second HTTP client or new framework. For three decisions, name an alternative, cost, failure sign and reversible next step. A specification is a document task with self-review; filling in the template is not a test result or permission to deploy the local fixture service.
Refresh first: Review states and revisions, Acquisition and quarantine.
Read an illustrative document
Illustrative contract — not an observed run
Given: submitted finding, revision 2, distinct fixture reviewer.
When: approve with expected_revision=2.
Then: current GET is approved/revision 3; one new audit event.
Retry: expected_revision=2 returns 409; no additional change.
Evidence: link actual before/after GET and audit transcripts.
Non-goal: authenticate a real reviewer or publish media.The precondition selects one state. The first action predicts a specific mutation; the retry predicts refusal with no new mutation. Until actual transcripts are retained, these are expected criteria, not passed evidence.
The document template is in SPEC.md. Reading it is guided practice, not independent evidence.
Make it measurable
Why is “the API handles errors well” insufficient?
Compare your answer · self-reviewed
It names no input, state, status or retained effect. Specify one refusal and show the actual before/after record and audit.
Separate evidence
Can a supplied width of 1920 prove the WAV has 1920 measured pixels?
Compare your answer · self-reviewed
No. Supplied API metadata and container observations have different sources. Label both; do not invent the missing connection.
Name the boundary
If export fails after review succeeds, has the whole workflow rolled back?
Compare your answer · self-reviewed
No. SQLite may retain the review while the NEW folder is partial. The per-record database transaction is not a cross-system rollback.
Change it, then build your own
One controlled change
Rewrite the illustrative approval criterion for rejection. Predict state, revision and audit changes, then add one refused self-review criterion using the Module 10 contract.
Your independent task
Author SPEC.md with your own classroom user/problem, explicit non-goals, evidence-layer table and at least six measurable criteria covering normal input, strict invalid input, review/stale/actor refusal, quarantine, dependency failure and restart. For each criterion name the actual evidence you will collect. Add three decisions with alternatives and limits; do not mark an unexecuted criterion passed.
What success looks like
A reader can predict specific input, state/status and retained effects for each criterion. Every observed claim has an evidence locator or is visibly pending. No invented measurement, cross-system rollback or public-deployment claim remains. This is self-review, not automated grading.
Hint 1 · a question
Who uses the tool, what decision do they make, and what evidence must survive?
Hint 2 · a concept cue
Use Given / When / Then / refusal / evidence / limitation for one changed input before expanding the table.
Hint 3 · a localized example
A stale request can be specified as 409 plus unchanged current record and unchanged audit length. The observed output must come from your run, not this sentence.
Need the complete worked solution?
Open SPEC.md from the kit. Trace it, close it, then try fresh inputs in your own files. Treat the attempt as guided; seeing the solution does not award a practical pass.
Course help is guidance, not independent evidence. With JavaScript, opening help records guidance locally; otherwise note it in your README. Reset does not erase that history.
Repair a missing claim or artifact
Replace adjectives with actions and observations. If a layer claims more authority than its input provides, narrow the claim. If you cannot name a repeatable observation, leave the criterion pending and plan a check instead of filling in an imaginary result.
Unknown or unobserved criteria remain pending. Document text is not executed or automatically approved.
Show it works on new inputs
Give another reader one new criterion without showing your implementation. Ask them to predict the result and identify the evidence needed. Record ambiguities and revise the contract. A self-recorded review is self-report; do not invent a reviewer observation.
Self-review: name the input, result, refused case and reason. Your local test output and explanation are separate from a quiz score; this page does not certify a pass.
Keep the idea
A useful contract predicts behavior and limits authority. It makes the integration accountable to evidence rather than a convincing success message.