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

Both sides previous revisionPrevious revision
Next revision		Previous revision
claude:dev_process [2026/05/01 06:00] – swap chainsaw enthusiasm phrase 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 27: Line 27:
   * **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 39: Line 41:
  
 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. 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 =====
claude/dev_process.1777615214.txt.gz · Last modified: by markus_fritsche