Organizing Comment Resolution and Linking Proof to Patches and Reviews

Good to continue from the feedback work list you created. You now have preserved source mail, verbatim reviewer wording, and small tasks with preliminary completion criteria. The next step is to make that list intelligible under pressure: determine which comments describe the same concern, which tasks depend on one another, which requests cannot all be satisfied at once, and which comments no longer apply to the V1 baseline.

The goal is not to reduce the number of comments by hiding them. It is to preserve every review obligation while creating a small set of evidence-backed repairs and clear reviewer responses. By the end of this lesson, each task should have a defined closure contract and explicit links to the patch that implements it and the reply that explains it.

---

Preserve comments; sort relationships around them

Do not merge or delete the feedback records from the previous lesson. A reviewer’s email remains a source artifact even when its concern is repeated, superseded, or shown not to apply.

Instead, add a relationship layer between feedback and tasks:

Record	What it represents	Must remain distinct?
Feedback record	One reviewer’s exact comment in its original V1 thread context	Yes
Issue group	A canonical engineering concern shared by one or more comments	No; it is derived and may evolve
Task	A bounded unit of investigation, code change, documentation, or human question	Yes, if it has distinct proof or scope
Patch link	The eventual commit or patch that implements a task, if code changes are needed	May be absent for explanation-only tasks
Reply link	The reviewer-facing response that closes the communication obligation	Required for substantive feedback

The central rule is:

Several comments may share one engineering task, but each substantive comment retains its own source record and response path.

For example, two reviewers may both ask why reset is deasserted at a particular point in probe. Their comments can be linked to one IG-RESET-ORDER issue group and one manual-evidence task. They remain separate feedback records because they may use different wording, identify different code locations, or require separate replies.

This is particularly important for an upstream DSA driver. A repeated request to “use the standard helper” may conceal two different concerns: one reviewer may be concerned with call context, another with resource ownership. Shared vocabulary is not enough to call comments duplicates.

---

Classify comments by meaning, scope, and required decision

Before assigning a relationship, compare comments on four dimensions:

1. Claim or request
   What is actually being questioned? An API choice, binding spelling, lifecycle issue, style concern, missing explanation, or hardware behavior?

2. Scope
   Which V1 patch, file, function, YAML property, Device Tree example, or register sequence is involved?

3. Condition
   Under what conditions does the concern apply? A particular kernel version, compatible string, port type, reset path, or error path may matter.

4. Requested outcome
   Is the reviewer asking for a code change, a rationale, a test, a different abstraction, or an answer to a question?

Only after this comparison should you assign one of the following relationships.

Relationship	Use it when	Do not use it when
REPEATS	Two comments ask for materially the same decision under the same conditions	The comments use similar words but concern different paths or APIs
RELATED	Concerns touch the same design area but require separate decisions	One task’s completion is necessary before another can be evaluated
DEPENDS_ON	A task cannot safely close until another task provides a result	The tasks merely happen to be implemented in the same patch
CONFLICTS_WITH	Two requested outcomes cannot both be implemented as stated	Reviewers offer compatible alternatives
SUPERSEDED	A later explicit reviewer message replaces or corrects an earlier request	You merely believe a newer comment is more important
NOT_APPLICABLE	Evidence shows the reviewed hunk, configuration, or premise does not exist in the exact V1 baseline	The task looks inconvenient, old, or difficult
RECORD_ONLY	The mail contains no actionable technical feedback, such as an acknowledgement	The comment is brief but still asks a technical question

Repeated comments: share the work, not the responsibility

A comment is repeated only if its engineering resolution would be identical. Capture a short rationale for that conclusion.

issue_groups:
  - id: "IG-PHYLINK-LIFETIME"
    title: "Validate phylink object lifetime during switch teardown"
    feedback_ids:
      - "FB-V1-008"
      - "FB-V1-019"
    relationship_rationale: >-
      Both comments question whether the same phylink instance can outlive
      the teardown path. Both point to the same allocation and removal flow.
    canonical_task_ids:
      - "TASK-PHYLINK-LIFETIME"

The task can be shared, but each linked feedback record needs an outcome. If the eventual implementation answers both reviewers, the replies may refer to the same patch and evidence while still addressing each person’s wording.

Linked comments: preserve the dependency

Many upstream concerns are linked without being duplicates. Consider a binding property that controls a hardware initialization path:

• The binding must define the property precisely.
• The driver must parse it consistently.
• The Device Tree example must use it correctly.
• Hardware programming may need manual evidence before the driver can safely act on it.

These are related tasks. The schema work may be ready now; the hardware behavior may be blocked on manual clarification. The work list must represent that distinction rather than treating the entire reviewer comment as “waiting.”

A dependency is a statement about proof, not implementation order. For example:

tasks:
  - id: "TASK-RESET-MANUAL-EVIDENCE"
    status: "BLOCKED"
    blocks:
      - "TASK-RESET-SEQUENCE-CODE"
    blocker: >-
      The available manual does not yet establish the required reset
      assertion and deassertion order.

  - id: "TASK-RESET-SEQUENCE-CODE"
    status: "WAITING"
    depends_on:
      - "TASK-RESET-MANUAL-EVIDENCE"

The code task does not become ready merely because an analogous switch driver uses a plausible sequence. For hardware behavior, only clear manual evidence or a recorded human decision can unblock it.

Conflicting comments: resolve the decision, not the people

A conflict exists when two proposed outcomes are mutually incompatible. Examples include:

• one reviewer requests a generic DSA helper while another requests a device-specific implementation;
• one request removes a binding property while another depends on preserving it for compatibility;
• a reviewer’s proposed reset sequence conflicts with the available manual.

Do not settle conflicts by counting reviewers, choosing the newest email, or asking an agent to choose the “most idiomatic” answer. Create a resolution task that identifies the decision and the evidence source needed to make it.

tasks:
  - id: "TASK-PORT-MODE-CONFLICT"
    type: "resolution"
    statement: >-
      Determine the target-kernel-supported representation for the CPU-port
      interface mode and decide which of the two reviewer suggestions is
      compatible with the binding and DSA call paths.
    linked_feedback:
      - "FB-V1-012"
      - "FB-V1-017"
    required_proof:
      - "Target-kernel DSA and phylink source references"
      - "Binding compatibility analysis"
      - "Explicit maintainer clarification if both interpretations remain viable"
    closure_rule: >-
      Record the chosen interpretation and why the alternative was not used;
      do not claim either reviewer agreed unless they explicitly did.

The resolution may produce a code change, an evidence-backed explanation, or a focused follow-up question. All are legitimate outcomes. Guessing is not.

Comments that no longer apply: prove the non-applicability

A comment is not obsolete merely because it is old or because the V1 series has been difficult to restore. Mark it NOT_APPLICABLE or SUPERSEDED only with a specific reason.

Acceptable reasons include:

• the reviewer commented on a hunk that is absent from the exact archived V1 baseline;
• the comment explicitly concerns a later series version rather than V1;
• a later message from the same discussion explicitly retracts or replaces the request;
• a configuration named in the comment is demonstrably impossible for the target driver or binding.

For each such disposition, capture a verification trail:

feedback_disposition:
  feedback_id: "FB-V1-023"
  status: "NOT_APPLICABLE"
  rationale: >-
    The comment names property vendor,legacy-delay. That property is absent
    from the restored V1 patch 3 and from its quoted diff hunk.
  proof:
    - type: "v1-patch-context"
      artifact: "artifacts/v1-mail/patch-3.eml"
      locator: "Diff for Documentation/devicetree/bindings/net/vendor,switch.yaml"
    - type: "baseline-commit"
      commit: "<restored-v1-tip>"
  reviewer_response_required: true
  response_plan: >-
    Explain briefly that this property is not present in V1 and quote the
    relevant current property, if the reviewer’s intended target is clear.

“Not applicable” is a closure type, not an excuse to omit a response. If the reviewer’s intent remains ambiguous, ask rather than declaring the matter closed.

---

Define closure before implementation

A task has two separate completion dimensions:

• Engineering closure: the implementation, investigation, or human decision is complete and evidenced.
• Communication closure: the original reviewer has an accurate response path, with no unsupported claim.

A task is fully closed only when both are satisfied.

The practical implication is simple: a clean build does not by itself close an upstream review task. Your closure proof must support the claim you will make to the reviewer.

Task outcome	Minimum engineering proof	Communication proof
Code fix	Focused diff, target-kernel rule or source evidence, relevant check logs and exit codes	Reply states what changed, where, and why it addresses the comment
Binding repair	YAML and example diff, binding check, relevant DTB check, compatibility rationale	Reply identifies the property or schema constraint changed
Explanation only	Evidence-backed rationale showing that no code change is needed	Direct, self-contained answer; add version note if useful
Rejected suggestion	Technical evidence showing why the suggested change is unsuitable	Respectful response that addresses the concern, not the reviewer personally
Hardware question	Exact manual reference or recorded human decision	State the confirmed fact or ask the focused unresolved question
Conflict resolution	Decision record with supporting evidence and any required maintainer clarification	Explain the chosen approach and the handling of the alternative
Not applicable	Exact V1 patch context, version evidence, or later explicit correction	Brief explanation of the mismatch, where a reply is needed

Be precise about the strength of each claim:

• “Fixed” requires an implemented change and validation evidence.
• “Explained” requires evidence supporting the explanation.
• “Blocked pending hardware clarification” requires a precise description of the missing fact.
• “Reviewer concern resolved” requires both engineering closure and a planned or sent response.
• “Accepted upstream” requires explicit upstream evidence. Do not infer it from silence.

At this point in the course, link existing build and baseline validation logs where they are relevant. Later modules will standardize the complete command runner, static checking, Sashiko gate, and optional hardware testing. Do not claim those later checks have passed before they have actually run.

---

Create a traceable closure contract

Add a closure section to every task. It should make it possible for an agent, a reviewer, or your future self to answer four questions:

1. What exact claim is this task allowed to make when closed?
2. What evidence supports that claim?
3. Which patch implements the outcome, if any?
4. Which reviewer-facing reply communicates the outcome?

A useful structure is:

tasks:
  - id: "TASK-DT-PORT-LABELS"
    issue_group: "IG-DT-PORT-LABELS"
    status: "OPEN"

    closure:
      allowed_claim: >-
        The binding, example, and driver use consistent port-label semantics
        for the target hardware.
      engineering_criteria:
        - "Target-kernel binding conventions have been compared."
        - "The YAML schema and example agree with driver property handling."
        - "Required binding and DTB checks have recorded successful results."
      evidence:
        - id: "EVID-041"
          type: "target-kernel-source"
          locator: "<file path and function or schema section>"
          supports: "Chosen binding convention"
        - id: "EVID-042"
          type: "check-log"
          artifact: "artifacts/checks/<run-id>/dt_binding_check.log"
          exit_code: 0
          supports: "Schema validation"
        - id: "EVID-043"
          type: "check-log"
          artifact: "artifacts/checks/<run-id>/dtbs_check.log"
          exit_code: 0
          supports: "Example validation"

    patch:
      planned_series_version: 2
      planned_subject: "dt-bindings: net: <vendor>: Correct port label schema"
      actual_commit: null
      actual_patch_message_id: null

    reviewer_reply:
      source_feedback_ids:
        - "FB-V1-006"
      planned_vehicle: "v2-changelog-and-inline-reply"
      draft_path: "review/replies/FB-V1-006.md"
      sent_message_id: null
      response_status: "NOT_DRAFTED"

The planned_* fields are intentionally separate from actual_* fields. Before the repair is implemented, you may know the expected patch location, but you do not yet have a commit ID or a sent-mail message ID. This prevents an agent from treating a plan as proof.

For an explanation-only task, make the absence of a patch explicit:

patch:
  code_change_required: false
  rationale: >-
    The target-kernel helper already provides the requested behavior; the
    concern is addressed by explaining the existing call path.
  actual_commit: null

A reviewer reply can be delivered in more than one form:

• a trimmed inline reply in the existing thread;
• a concise note in the next revision’s patch changelog;
• both, when a direct answer and a version summary help reviewers.

Record the selected vehicle deliberately. The official guidance makes clear that comments need responses and that changes between versions should be documented for the next review. Do not use a vague changelog line such as “Address review comments” as the only trace of a complex concern.

---

Make the patch and reply mapping auditable

When implementation begins, update the task with immutable identifiers rather than prose such as “fixed in patch 2.”

Patch positions can change when you split, merge, reorder, or drop patches. Use stable IDs wherever possible:

Link	Record now	Record after creating the next series
Source feedback	V1 message ID, patch message ID, hunk context	Unchanged
Planned implementation	Intended subject and purpose	Actual commit ID and final patch message ID
Patch range	Expected series scope	Exact submitted range and series version
Reviewer response	Draft file and intended reply method	Sent reply message ID and final text location
Evidence	Artifact paths and pending checks	Artifact checksum, run ID, exit code, and result

A reviewer response should be self-contained enough that they do not need to reconstruct your private task database. It should normally contain:

1. a direct acknowledgement of the concern;
2. the outcome, whether code change, rationale, deferral, or question;
3. the precise location of the change, if one was made;
4. the evidence limit, especially for hardware behavior;
5. a concise thanks.

For example, do not write:

Fixed reset handling.

A bounded response, after evidence exists, would be closer to:

Thanks for pointing this out. I changed the reset lifetime handling in <function> so the resource is released on the probe error path as well as normal removal. The change is in <patch subject>; the relevant target-kernel managed-resource pattern and recorded build results are linked in the revision notes. I did not change register reset ordering because the available manual section does not establish that behavior.

That response distinguishes a verified lifecycle fix from a deliberately blocked hardware change. It gives the reviewer a useful answer without pretending that missing hardware evidence has been found.

---

Run a sorting pass that an AI agent can assist, but not decide alone

For the V1 work list, use a repeatable pass rather than informal cleanup.

1. Generate candidate groups.
   Let the agent cluster records by touched file, function, binding property, hardware feature, and key terms. Treat these only as candidates.

2. Compare the original evidence.
   Read the complete comment and quoted hunk. Confirm the claim, scope, condition, and requested outcome before accepting a relationship.

3. Assign exactly one disposition to each feedback record.
   A record may belong to several issue groups, but its basic disposition should be unambiguous: actionable, repeated, related, conflict, superseded, not applicable, or record only.

4. Create or refine tasks.
   Split tasks whenever the proof types differ. A schema check and a hardware-manual question should not share one closure criterion.

5. Declare proof and reply requirements.
   Add required evidence, planned patch handling, and a reviewer-response vehicle before any code edit.

6. Perform a human audit.
   Review all conflict, superseded, and not-applicable classifications. These are the categories most likely to hide an unjustified assumption.

A tool-neutral agent instruction can be kept narrow:

Read feedback records and task records only. Do not edit kernel source.

For each feedback record:
- Propose candidate repeated, related, dependency, conflict, superseded,
  or not-applicable relationships.
- Quote the exact evidence used for each proposal.
- Identify the claim, scope, condition, and requested outcome.
- State whether a shared task is justified.
- List the proof required to close the associated task.
- Require a patch link or an explicit no-code-change rationale.
- Require a reviewer-response plan.

Do not:
- alter verbatim reviewer wording;
- mark any task closed;
- infer hardware facts from V1 code, analogous drivers, or unclear manuals;
- treat a build result as proof of hardware behavior;
- declare a comment obsolete without exact source evidence.

The agent can reduce clerical effort, find likely relationships, and point out missing links. The human reviewer decides whether two comments truly mean the same thing and whether the proposed evidence is sufficient.

---

Final audit: can every comment be traced forward?

Before leaving this module, produce a compact closure report. It should answer the following questions without requiring anyone to search the entire thread manually:

• Does every substantive V1 feedback record have a disposition?
• For every REPEATS relationship, is there a rationale and a shared canonical task?
• For every DEPENDS_ON relationship, is the blocking proof identified?
• For every CONFLICTS_WITH relationship, is there a resolution task rather than an unsupported choice?
• For every NOT_APPLICABLE or SUPERSEDED record, is the source evidence recorded and is a reviewer response planned?
• Does every task define engineering criteria, evidence artifacts, patch handling, and reviewer-response handling?
• Are planned patch IDs clearly distinct from actual commit IDs and sent-mail message IDs?
• Are hardware-programming tasks blocked when the manual evidence is unclear?

A simple summary table is useful for the project dashboard:

Status	Meaning	May an agent edit code?
READY	Scope and required proof are clear	Yes, within task constraints
WAITING	Another task must finish first	No
BLOCKED	Human decision or missing authoritative evidence is required	No for the blocked scope
IMPLEMENTED	Diff exists but proof is incomplete	No further scope expansion
VERIFIED	Engineering evidence is complete	Yes only for response preparation or separate tasks
CLOSED	Evidence, patch mapping, and response path are complete	No, unless reopened by new evidence
NOT_APPLICABLE	Non-applicability is evidenced and communicated	No code change for that record

---

Key takeaways

Sorting feedback is not a way to make review comments disappear. It is a way to preserve every reviewer obligation while avoiding duplicated work and unsupported fixes.

• Keep original feedback records immutable; add relationships and issue groups around them.
• Treat repeated comments as shared engineering work with separate reviewer-response obligations.
• Represent dependencies explicitly, especially when safe DSA or binding work can continue while hardware evidence is missing.
• Resolve conflicting requests with target-kernel evidence, binding analysis, manual evidence, or a focused human question—not reviewer counting or AI preference.
• Mark a comment not applicable only with exact V1 or thread evidence, and still explain that conclusion to the reviewer when appropriate.
• Define closure up front: evidence, implementation or no-change rationale, patch mapping, and reply mapping.
• Never let a planned patch, successful build, analogous driver, or polished AI explanation stand in for proof it cannot provide.

Next, you will begin the hardware-evidence discipline: extracting driver-relevant facts from the switch manual, linking them to exact sections, and marking unclear or contradictory material before any hardware-programming change is allowed.