Episode: Fan Control Interface Plan

EPISODE-GOAL

Plan the use of the MI25 driver interfaces for the fan-control service, translating documents/05-mi25-driver-interfaces.md into a concrete service design.

EPISODE-ACCEPTANCE

• Does the plan map every interface in documents/05-mi25-driver-interfaces.md to a concrete use: control, monitoring, fingerprinting, or explicitly unused?
• Does the plan specify the exact sysfs paths and attribute semantics the service will read and write?
• Does the plan specify the startup sequence: discovery, probe, pwm1_enable=1, initial PWM write?
• Does the plan specify the control algorithm (stage tables, interpolation, ramp, delta thresholds) in enough detail to implement without re-derivation?
• Does the plan specify how the service records driver version and kernel release, and how it distinguishes in-tree from out-of-tree drivers?
• Does the plan state the debugfs policy (optional diagnostics only) and the /dev and /run policy (unused)?
• Does the plan specify the reporting format and rate?
• Does the plan specify the systemd unit design: name, ordering, restart policy, privileges?
• Does the plan explicitly defer the runtime failure policy to the research-spike TODO, and list the open questions the spike must answer?
• Is the plan reviewable in one sitting?

EPISODE-RISKS

• Is the interface map in documents/05-mi25-driver-interfaces.md accurate enough to plan against, given the driver-version drift?
• Does the service need anything beyond sysfs hwmon for reliable control?
• Will the plan’s discovery and probe strategy survive a changed card number at boot?
• Does the plan overcommit to driver internals that a future driver could change?

EPISODE-TASKS

• Review documents/05-mi25-driver-interfaces.md and prompts/features/02-fan-control.md as the planning inputs.
• Classify each documented interface as control, monitoring, fingerprinting, optional diagnostics, or unused.
• Specify the control surface: pwm1_enable, pwm1, temp2_input (junction), temp3_input (mem), temp1_input (edge).
• Specify the fingerprinting surface: /sys/module/amdgpu/version, /proc/modules taint flags, uname release.
• Specify the monitoring surface: gpu_busy_percent, freq1_input, freq2_input, power1_input, debugfs when available.
• Specify the startup sequence and the retry behavior while the hwmon node appears at boot.
• Specify the control algorithm with concrete constants, derived from the reference actor6 behavior.
• Specify the reporting format, rate, and destination.
• Specify the systemd unit design.
• List the open questions the research spike must answer before implementation.
• Write the plan document, update the feature file if the plan changes requirements, update TODO, commit, and write a record.

EPISODE-OUTPUT

A rough draft of documents/06-fan-control-service-plan.md for human review, plus the record of the episode in records/.

EPISODE-FILES

• prompts/episodes/03-fan-control-interface-plan.md — new
• documents/06-fan-control-service-plan.md — new
• prompts/features/02-fan-control.md — modify only if the plan changes requirements
• records/03-fan-control-interface-plan.md — new
• TODO.md — modify