Practice feedback
Practice feedback is feedback on an observable way of working, such as keeping a change reviewable, explaining why it is needed, or responding constructively to a reviewer.
When practice reviews are enabled, Hephaestus uses AI to review eligible pull requests, merge requests, and issues against the practices configured for your workspace. It posts the resulting feedback as a comment on the work.
The feedback is advisory. It does not approve a change for merge, grade the developer, or replace human review.
Pull requests and merge requests
In this guide, change request means a GitHub pull request or a GitLab merge request.
What happens
- You open an eligible, non-draft change request.
- Hephaestus reads the change, its description, commits, and relevant discussion.
- It checks the work against the practices enabled for the workspace.
- It posts a summary comment. Feedback tied to a specific changed line can also appear as an inline comment.
Reviews usually complete within 2 to 5 minutes. Large changes can take longer.
Read the summary
The summary can include:
- a practice the work demonstrated well
- a concern that applies to the whole change, such as a missing explanation or an unfocused set of commits
- links to inline comments on specific changed lines
- an explanation of why the practice matters and what to try next
When Hephaestus finds a clear positive practice, the summary can name it. This is feedback on the practice, not an approval of the change.
Read inline comments
For feedback tied to a changed line, an inline comment can explain:
- what Hephaestus noticed
- why it matters
- what you could change
Some comments include a suggested code change. Check it before applying it.
Run the review again
After you push new commits, add this comment at the start of a change-request comment:
/hephaestus review
The command is case-insensitive. Text before the command prevents it from being detected.
The command is ignored for closed change requests. Whether manual review commands and reviews of merged requests are allowed depends on the workspace settings.
What code is reviewed
Hephaestus evaluates lines added by the change request. Existing code can be used as context but is not reported as a new concern.
Some practices use change-request metadata instead of code, including the description, commit history, and review discussion.
Issues
Hephaestus can also give practice feedback on issues. Depending on the practices configured for the workspace, a review can run when an issue is created, labeled, or closed.
Issue feedback appears as a single comment. It can cover practices such as:
- stating the observed and expected behaviour
- giving enough information to reproduce a problem
- keeping the issue focused on one concern
- recording the reason for closing an issue
Closed issues do not receive a new feedback comment.
Practices and severity
The exact practices depend on your workspace. Common areas include:
- packaging work for review
- writing actionable issues
- acting on review feedback
- testing changes
- maintainable code
- security and reliability habits
Feedback can carry one of four severity labels:
| Severity | Meaning |
|---|---|
| CRITICAL | A security vulnerability, data-loss risk, or production crash |
| MAJOR | A functional problem or missing safety mechanism |
| MINOR | A smaller maintainability, readability, or workflow concern |
| INFO | An observation with no direct quality impact |
Severity helps order the feedback. It is not a grade or merge decision.
Linked documentation
If your workspace connects an Outline team wiki, Hephaestus can read selected documents linked from a change request or issue. This can help it use an architecture decision or design document instead of guessing at the missing context.
Hephaestus only reads collections a workspace admin chose to mirror. It does not write to Outline. Connecting your own Outline account under Settings → Connected accounts lets Hephaestus attribute documents you wrote to you.
Stop comments and reminders
Open Settings → Practice feedback and turn off Comments and Slack reminders to stop new practice-feedback comments on issues, pull requests, or merge requests you author and Slack reminders sent to you.
This setting controls delivery only. Reviews can still run, their findings remain stored and may be visible to workspace admins, and earlier comments and findings are not deleted.
Draft change requests are skipped when the workspace's Skip drafts setting is on. Marking a draft ready does not always start a review by itself; use /hephaestus review when manual review commands are enabled.