Polisher-Control/docs/11-feature-request-intake.md

---
title: Polisher-Control Feature Request Intake
status: draft
requested_by: Antoine Letarte
generated_by: Nick / Hermes
project: P11-Polisher-Fullum
repo: polisher-control
source_truth: false
created: 2026-06-02
privacy: technical-only
---

# Feature Request Intake — Polisher-Control

## Purpose

Use this note when Antoine or Cédric proposes a new feature for `polisher-control`.

The goal is to avoid coding a feature into the wrong layer. Some requests belong in the machine controller, some belong in `polisher-post`, and some belong in `polisher-sim`.

## Fast classification

Before implementation, classify the request.

| Class | Belongs where | Examples |
|---|---|---|
| Execution feature | `polisher-control` | manual UI behavior, host state machine, Teensy loop, drive/sensor integration, telemetry logging, alarms, `/data/` artifacts |
| Contract feature | `polisher-control` + `shared/schemas` + usually `polisher-post` | new telemetry channel, new protocol field, new log field, new machine-capability property |
| Planning/intelligence feature | `polisher-sim` / `polisher-post` | choosing pass strategy, metrology interpretation, calibration updates, optimization, dwell planning |
| Safety/scope feature | approval-gated | interlock behavior, E-stop response, force limits, fault reset policy, remote operation, powered manipulation modes |

Rule: if the feature decides **what polishing should be done**, it is probably not a `polisher-control` feature. If it executes/logs/enforces what was already approved, it probably is.

## Intake template

Copy this block into an issue, PR, or `docs/nick-generated/YYYY-MM-DD-feature-name.md` when scoping a feature.

```markdown
---
title: Feature Intake — <short feature name>
status: draft
requested_by: Antoine / Cédric
generated_by: Nick / Hermes
project: P11-Polisher-Fullum
repo: polisher-control
source_truth: false
created: YYYY-MM-DD
privacy: technical-only
---

# Feature Intake — <short feature name>

## 1. Requested behavior

- What should the operator/system be able to do?
- What problem does this solve?
- Who requested it?

## 2. Classification

- [ ] Execution feature in `polisher-control`
- [ ] Contract feature touching schemas/protocol/telemetry/logs
- [ ] Planning/intelligence feature that belongs upstream
- [ ] Safety/scope feature requiring Antoine approval

Rationale:

## 3. Operator-visible behavior

- UI controls / screens / prompts:
- Normal workflow:
- Fault/warning workflow:
- What is logged as operator action:

## 4. Affected layers

- Host controller:
- Teensy firmware:
- Host ↔ Teensy protocol:
- Telemetry channels:
- Run/manual-session logs:
- Machine capability profile:
- Shared schemas:
- Tests:
- Docs/checklists:

## 5. Safety implications

- Does it affect force, motion, brakes, interlocks, E-stop, watchdog, or reset behavior?
- Does it allow motion in a new condition?
- Does it change any limit or threshold?
- Does it require a new refusal/NACK reason?
- Does it need a hardware interlock or physical confirmation?

Safety decision:

- [ ] No safety behavior change
- [ ] Safety behavior change; Antoine approval required before implementation

## 6. Contract implications

- New/changed protocol messages:
- New/changed telemetry channels:
- New/changed log fields:
- New/changed machine capability fields:
- Backward compatibility / schema version impact:

Contract decision:

- [ ] No schema/protocol contract change
- [ ] Contract change; update schemas/examples/docs/tests together

## 7. Acceptance checks

- [ ] Host-side unit test:
- [ ] Firmware compile/build check:
- [ ] Protocol encode/decode test:
- [ ] Schema/example validation:
- [ ] State-machine transition test:
- [ ] Telemetry channel consistency check:
- [ ] Safety refusal/fault test:
- [ ] Commissioning checklist update:
- [ ] Manual/operator workflow check:

## 8. Open questions

- For Antoine:
- For Cédric:
- For source-spec update:

## 9. Implementation notes

- Suggested branch:
- Suggested first PR chunk:
- Suggested follow-up chunk:
```

## Approval gates

Ask Antoine before implementing when a request changes any of these:

- v1 scope boundary;
- safety/interlock behavior;
- force limits, braking, fault/reset policy;
- host ↔ Teensy protocol semantics;
- telemetry channel names, units, rates, or meanings;
- schema versions or required fields;
- boundary between `polisher-control`, `polisher-post`, and `polisher-sim`;
- any powered manipulation / Zero-G / remote-control behavior.

## Implementation chunking recommendation

For most features, keep PRs small:

1. **Spec/doc PR:** feature intake, acceptance checks, schema/protocol sketch.
2. **Host PR:** state machine / UI workflow / logs / tests.
3. **Firmware PR:** message handling / loop behavior / telemetry / compile check.
4. **Integration PR:** end-to-end dry-run, examples, commissioning checklist.

Do not mix a safety contract change with broad unrelated refactors.