Repository navigation
📝 [docs] pr: explain changed files with review comments - #26
Conversation
- Add Purpose, What changed, and Why it matters notes on PR files and critical lines. - Refresh owned notes safely and preserve human replies and review requirements. - Wire Builder, QA, and UI handoffs; verify format and installation checks.
There was a problem hiding this comment.
Purpose: This is the main instruction page for agents working in Super Board.
What changed: It points agents to the new three-part format for comments on a pull request.
Why it matters: Agents can find the rule while doing their normal work.
There was a problem hiding this comment.
Purpose: This template adds Super Board instructions to a project during installation.
What changed: It includes the file-comment rule and keeps routine status comments short.
Why it matters: Projects that install Super Board get the same readable review notes.
There was a problem hiding this comment.
Purpose: This guide tells the PR author how to explain changed files on GitHub.
What changed: It covers file summaries, important-line comments, later edits, and failed posting attempts.
Why it matters: You can understand each file without losing other people's comments or seeing repeated notes.
There was a problem hiding this comment.
Purpose: This guide describes how tasks move through building, testing, and review.
What changed: It adds explanation notes before handoffs and keeps them separate from requests to fix code.
Why it matters: You get context for the change without the board mistaking an explanation for a new bug.
There was a problem hiding this comment.
Purpose: This file sets the shared writing format for Super Board.
What changed: It defines Purpose, What changed, and Why it matters for comments beside files and important lines.
Why it matters: Every note follows the same short structure, so you know where to look.
There was a problem hiding this comment.
Purpose: These instructions guide the agent that builds a task and opens its pull request.
What changed: They ask for explanation notes on finished work, partial drafts, and later fixes.
Why it matters: The notes arrive with the work and stay useful when the code changes.
There was a problem hiding this comment.
Purpose: These instructions guide the agent that tests a board task.
What changed: They ask the testing agent to refresh file notes after pushing tests, evidence, or fixes.
Why it matters: New test and evidence files also get an explanation.
There was a problem hiding this comment.
Purpose: This is the brief for a testing run that can open its own fix pull request.
What changed: It tells that run to add and check the same file and important-line notes.
Why it matters: Fixes found during testing get the same readable context as regular tasks.
There was a problem hiding this comment.
Purpose: These instructions guide the agent that reviews a pull request before merging.
What changed: They separate author explanations from findings while keeping human replies part of review.
Why it matters: An explanation cannot approve the code or hide a person's request for a change.
There was a problem hiding this comment.
Purpose: These instructions guide a run that improves an app's appearance.
What changed: They add file notes before handing over its draft pull request, including screenshot files.
Why it matters: You can see what each design change and image is there to show.
There was a problem hiding this comment.
Purpose: This check catches examples that drift from Super Board's writing formats.
What changed: It checks the three labels and makes sure an author note has no review-finding header.
Why it matters: The shared example stays short and does not look like a request to fix the code.
| old/new side. Never guess line numbers from an earlier checkout. | ||
| 3. Match existing author notes by path, subject type and stable marker key. Only change | ||
| notes whose author is the current authenticated identity and whose marker identifies | ||
| this workflow's note. Preserve all other comments, including human edits and replies; |
There was a problem hiding this comment.
Purpose: This step decides which existing notes the agent may update.
What changed: It requires a matching author and note marker, and preserves edits or ownership it cannot confirm.
Why it matters: Refreshing the explanation must not overwrite a person's words.
- Let GitHub infer line comments from line and side. - Verify file and inline posting against the live draft pull request.
| on a current changed file. Never delete a thread or resolve human replies to tidy up. | ||
| - Timeout or uncertain write result: read the comments again before doing anything else. | ||
| Match the intended marker, path, anchor and body. If its outcome is still unknown, stop | ||
| and report it. Never blindly replay a create or submit request. |
There was a problem hiding this comment.
Purpose: This step handles a request that may have posted a comment before the connection failed.
What changed: It checks GitHub first and stops if the result is still unknown.
Why it matters: Running the same post again could leave you with duplicate comments.
| 2. **Gate 1 — thread scan.** Read threads and replies. [PR author notes](../super-board/references/pr-author-notes.md) | ||
| alone are explanations, not findings or approval. Human questions or change requests | ||
| in those threads still follow the normal review/blocking flow; the marker exempts no | ||
| replies. Never auto-resolve them or bypass GitHub's conversation-resolution requirements. |
There was a problem hiding this comment.
Purpose: This step tells the reviewer how to read a thread that starts with an explanation.
What changed: It keeps human questions and change requests in the normal review process.
Why it matters: The explanation label cannot hide a concern or bypass GitHub's required conversations.
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
1 participant
Note
Draft · ready for review
Problem
The PR description explains the whole change, but it can still be hard to understand an individual file. Readers have to work out what that file does and why its changes matter.
Solution
This is a shared rule for the agents that write PRs. It does not add a new background service or an automated merge check.
Acceptance criteria
Iteration history
Risk
🟢 Low · This changes agent instructions and one existing format check. Agents must follow the rule; GitHub does not enforce the writing format. Existing approval and conversation rules still apply.