Zettelkasten

User Tools

Site Tools

You are here: start » claude » dev_process
claude:dev_process

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
claude:dev_process [2026/04/30 12:08] – mirror 8-phase dev process from memory markus_fritscheclaude:dev_process [2026/05/02 15:57] (current) – Phase 6: add worked example for 'state the contract explicitly' (patch 0012, h264 SCALING_MATRIX) markus_fritsche
Line 15: Line 15:
 ===== Phase 3 — Baseline Measurements ===== ===== Phase 3 — Baseline Measurements =====
  
-Take concrete measurements //before// any changes (strace, perf, logs, UART capture, register dumps — pick what fits the problem). Record baseline explicitly; do not rely on memory or estimates.+Take concrete measurements //before// any changes. Paste raw output into DokuWiki at capture time — verbatim, not paraphrased. The Phase 5 artifact is the raw data, not Claude's summary. 
 + 
 +**Real data, not theatre.** Phase 3 exists to use AI capacity for absorbing wide, low-level instrumentation a human reader would skim past. Attaching strace / perf / ftrace / eBPF / custom tripwires to the process under test is real Phase 3; scraping mpv's stdout dropped-frame counter is not. Discriminator: if a human with bash and grep could produce the same baseline, it isn't Phase 3 yet — go down to the syscall / call-path / MMIO / register layer. 
 + 
 +**Anti-fabrication:** 
 + 
 +  * Every cited value traces to a visible tool invocation or verbatim paste-in. If a measurement wasn't taken, write "not measured" — never an estimate, inference, or recall from training / prior sessions / sibling-host memory. 
 +  * Raw before derived. A derived number (FPS, p99, error rate) appears alongside the raw stream it came from, never alone. 
 +  * Rig failure is the finding. Empty strace, dead UART, perf counter that didn't increment → that //is// the Phase 3 result. Loop back to Phase 2 to fix the rig; do not synthesize plausible-looking baseline data to keep momentum.
  
   * **If baseline reveals the Phase 1 metric was tracking the wrong thing → loop back to Phase 1** with the corrected target.   * **If baseline reveals the Phase 1 metric was tracking the wrong thing → loop back to Phase 1** with the corrected target.
   * Example: "max H.264 FPS" Phase 1 metric, but baseline shows DMA-setup + sync overhead dwarfs decode → real metric is bytes-copied-per-second / EGL surface-import time, not FPS.   * Example: "max H.264 FPS" Phase 1 metric, but baseline shows DMA-setup + sync overhead dwarfs decode → real metric is bytes-copied-per-second / EGL surface-import time, not FPS.
 +
 +**Measurements describe what the system //does//, not what it //should do//.** Baseline data is evidence, not a specification. Do NOT derive API call sequences, struct layouts, or parameter values from observed behaviour (strace, perf, example output). Observable behaviour may reflect bugs, workarounds, or implementation accidents — anything you copy from it inherits those.
  
 ===== Phase 4 — Plan ===== ===== Phase 4 — Plan =====
Line 30: Line 40:
 ===== Phase 6 — Implementation ===== ===== Phase 6 — Implementation =====
  
-Execute the plan. Scope strictly to what was planned — resist feature creep, refactor-creep, "while I'm here" cleanups, and chainsaw enthusiasm. If a plan revision is needed mid-implementation, surface it explicitly and re-enter Phase 4.+Execute the plan. Scope strictly to what was planned — resist feature creep, refactor-creep, "while I'm here" cleanups, and over-eager scope expansion. If a plan revision is needed mid-implementation, surface it explicitly and re-enter Phase 4. 
 + 
 +**Contract before code.** Before writing or modifying any call site: 
 + 
 +  * Read the API contract — kernel docs, header comments, and upstream source for every call touched. 
 +  * State the contract explicitly before implementing against it (in the plan, the commit message, or a comment — somewhere reviewable). 
 +  * If the contract cannot be found: stop and surface the gap. Don't infer it from baseline behaviour or sibling code. 
 + 
 +**Copying from baseline measurements is not implementation. It is transcription of potentially broken behaviour.** A deliverable that matches baseline bytes but violates the API contract is not a deliverable — it is a deferred bug. 
 + 
 +==== What "state the contract explicitly" looks like ==== 
 + 
 +Worked example: ''0012-h264-omit-scaling-matrix-frame-based.patch'' in ''~/src/ohm_gl_fix/phase6/step1/''. The commit message opens with the contract before any code: 
 + 
 +<code> 
 +VAAPI signals "explicit scaling lists are present in the bitstream" 
 +implicitly: the consumer (ffmpeg-vaapi, mpv, etc.) sends a 
 +VAIQMatrixBufferH264 alongside RenderPicture iff 
 +sps_scaling_matrix_present_flag || pps_scaling_matrix_present_flag. 
 +When the bitstream uses default (flat) scaling, no IQMatrixBuffer 
 +arrives [...] 
 + 
 +Earlier draft of this patch unconditionally omitted SCALING_MATRIX in 
 +FRAME_BASED. That's corpus-correct (bbb has no explicit scaling 
 +lists) but the wrong predicate: the kernel-side gating is by 
 +"matrix-supplied vs. not," not by decode mode. Streams that signal 
 +explicit scaling lists must submit SCALING_MATRIX in either mode. 
 + 
 +Contract verification (audit_0008_decode_params_2026-05-01.md + 
 +hantro_h264.c::assemble_scaling_list): the kernel uses the supplied 
 +matrix when SCALING_MATRIX is in the control batch and falls back 
 +to spec-defined defaults when absent. Mode-independent. 
 +</code> 
 + 
 +What this gets right: 
 + 
 +  * **Contract first** — per-control rules cited from kernel doc (''ext-ctrls-codec-stateless.rst:752''), kernel driver (''hantro_h264.c::assemble_scaling_list''), and sibling implementation (gst-plugins-bad commit 9e3e775) //before// any patch hunks. 
 +  * **Corpus-correct ≠ spec-correct, called out by name** — the rejected predicate ("omit SCALING_MATRIX in FRAME_BASED") //did// match the BBB baseline. It still got rejected, because the contract said the gate is "matrix-supplied vs. not," not "decode mode." This is exactly the Phase 3-derived-implementation trap. 
 +  * **Then** the diff implements one branch per contract clause: SPS/PPS/DECODE_PARAMS always, SCALING_MATRIX iff ''matrix_set'', SLICE_PARAMS iff SLICE_BASED, PRED_WEIGHTS iff SLICE_BASED + ''V4L2_H264_CTRL_PRED_WEIGHTS_REQUIRED''. 
 + 
 +Mirror format anywhere reviewable: PR description, commit message body, plan section, or a header comment block. The shape is //contract clauses with citations → code that maps 1:1 to those clauses//.
  
 ===== Phase 7 — Verification Measurements ===== ===== Phase 7 — Verification Measurements =====
Line 52: Line 102:
 Several recurring failures in prior work codify into individual rules — observer-first, simulate-before-flash, three-strikes-then-verify, "trust eyes not vibes," scope-strictly-to-plan, no-fake-dry-run. Those are all symptoms; this loop is the structural fix. Use it as the spine and let those rules show up as rejection patterns inside the appropriate phases. Several recurring failures in prior work codify into individual rules — observer-first, simulate-before-flash, three-strikes-then-verify, "trust eyes not vibes," scope-strictly-to-plan, no-fake-dry-run. Those are all symptoms; this loop is the structural fix. Use it as the spine and let those rules show up as rejection patterns inside the appropriate phases.
  
-//"The seven-year-old with the chainsaw can do real work. Watch the blade, not the smile."//+ 
 + 
  
claude/dev_process.1777550904.txt.gz · Last modified: by markus_fritsche