Skill: F Prime maintenance — the doctrine of minimal effect

When maintaining existing code the goal is the minimal change necessary to complete the task. Focus explicitly on the task at hand and on low-hanging-fruit technical-debt cleanup. Do not rework the design, the architecture, or anything else. If a larger rework appears necessary (for example, to avoid adding technical debt), propose it and obtain an engineer's approval before doing it.

Creating new components, topologies, or build modules is not maintenance; follow .github/agents/fprime-development.agent.md for that work. This skill applies alongside the phase skills whenever the task touches code that already exists.

1. Scope the task before touching code

• State the task in one sentence: the defect, behavior change, or update, and its acceptance criterion (the test that fails today, the warning that must go away, the API that must be adopted).
• Identify the smallest set of files and symbols that must change to meet it. That set is the scope; everything else is out of scope unless §3 or §4 admits it.
• Read the surrounding code and the component docs/sdd.md first. The change must fit the existing design, not the design you would have chosen.

2. Make the minimal change

• Change only what the task requires. Preserve existing interfaces (ports, commands, events, telemetry, parameters, public signatures), file layout, naming, and all behavior outside the task.
• Follow the surrounding conventions even where they differ from newer code elsewhere. fprime-cpp-design still governs every line you write.
• Do not rename, reorder, move, or reformat code the task does not touch. Run clang-format on changed files only.
• Do not modernize, generalize, or add abstraction, configuration, or features "while you are here".
• Update only the artifacts the change invalidates: unit tests for the changed behavior, the component docs/sdd.md, and the docs/ pages that describe it.
• Fit the tests to the change: a regression test for the defect and one test per behavior the task added or changed. Do not add tests for behavior the task did not touch; record coverage gaps as future work (§5). Once the new tests pass, run the consolidation step in fprime-unit-testing §1 so shared sequences become helpers or rules.
• Keep comments short and about the code as it now is. Do not add comments that narrate the change, describe the old behavior, or justify the new code against it; that context belongs in the PR description.
• Keep the diff reviewable: every hunk must map to the task statement or to a cleanup item declared under §3.

3. Low-hanging fruit — permitted cleanup

Technical-debt cleanup is permitted only when it is adjacent to the task (a function or file you are already editing), mechanical and behavior-preserving, and small enough to verify by inspection. Examples:

• a typo, stale comment, or outdated doc line the change made you read
• a magic literal on a touched line replaced with the existing named constant
• dead code or an unused include the change makes obviously dead
• a missing override, const, nullptr, or fixed-width type on a touched declaration
• an unchecked return code on a call you are already modifying

Anything larger is not low-hanging fruit, however beneficial. List each cleanup item in the PR description so reviewers can separate it from the task itself.

4. Rework requires engineer approval

Sometimes the minimal change would add technical debt, or the task cannot be completed within the existing design. Do not decide this alone:

1. Stop before starting the rework. Leave the minimal change, if one exists, in a clearly described state.
2. Write a short proposal: why the minimal approach is inadequate, the rework and its extent (files, interfaces, behavior affected), alternatives considered, and the risk.
3. Present it to the responsible engineer — the requesting user, the component maintainer (maintainer-lookup), or an issue for CCB review per GOVERNANCE.md — and wait for explicit approval. Silence is not approval.
4. Once approved, deliver the rework separately from the fix (its own PR, or clearly separated commits) so each can be reviewed and reverted independently.

Rework includes changing an FPP interface, restructuring a component or its state, changing a framework type or OSAL contract, moving code across modules, wide renames, replacing an algorithm or data structure, and any change whose footprint exceeds the scope set in §1.

5. Out-of-scope findings

Record defects, debt, or design concerns you notice but do not fix under §3 — in an issue, or under "Future work" in the PR description — rather than fixing them silently. This mirrors the reviewer-side rule in pr-diff-scoping: preexisting issues are future work, not part of the current change.

6. Checklist before opening the PR

• Every hunk maps to the task statement or a declared §3 cleanup.
• No interface, layout, or behavior changed beyond the task.
• Any rework was approved by an engineer beforehand and is separated from the fix.
• Tests, docs/sdd.md, and docs/ updated only where the change invalidated them; new tests trace to the task and were consolidated.
• No comment narrates the change or the old behavior.
• Out-of-scope observations recorded, not fixed.
• PR description distinguishes the fix, declared cleanup, and future work.