Heimdall: Your First PR Review

Once you've connected Heimdall and installed the GitHub App, it reviews every PR automatically. Here's what to expect and how to get the most out of it.

Not set up yet? Go to Settings → Apps → Heimdall, subscribe, and install the GitHub App on your org. Then open any PR — Heimdall comments within seconds.

Reading the review comment

Heimdall posts a single structured comment on every PR. Here's what each section means:

## Heimdall Review - MEDIUM

Good refactor overall. The auth token refresh logic is cleaner, but there are two
callers of the old refreshToken() function that weren't updated.

**Concerns:**
- auth.service.ts line 47: refreshToken() is still called by session.middleware.ts
  and token.validator.ts — both will break after this change

**Test checklist:**
- [ ] Verify token refresh still works when the access token is expired but refresh token is valid
- [ ] Confirm session.middleware.ts handles the new return shape from the updated function
- [ ] Test concurrent refresh requests don't produce duplicate sessions

**Security scan:**
- [MEDIUM] Sensitive data logged: token value visible in logger.debug() call on line 83

**Intent:** 78% match — PR description says "refactor token refresh" but also modifies
session expiry logic which isn't mentioned

**MCI completeness:** 2 missed callers of refreshToken()

---
Heimdall - Auto-merge: not eligible

Risk levels

Level	Meaning	Auto-merge eligible?
LOW	No auth, DB schema, or API contract changes. No concerns flagged.	Yes — if no concerns
MEDIUM	Logic changes with possible edge cases, or some concerns flagged.	No
HIGH	Auth, payments, DB migrations, breaking API changes, or critical security findings.	No

Acting on findings

Concerns

Concerns are things Heimdall believes need attention before merge. They're specific — always referencing a file, function, or line. Work through them before merging.

If you believe a concern is wrong, mention @heimdall on the relevant line to explain why. Heimdall will re-evaluate and either confirm the concern or acknowledge the dismissal.

Security findings

CRITICAL findings should always be addressed before merge. HIGH findings on a LOW-risk PR escalate the risk rating and should be reviewed. MEDIUM findings are informational — use your judgment.

If a security finding is a false positive (common with patterns that look like secrets but aren't):

@heimdall the "token" in logger.debug() on line 83 is a CSRF token used for UI rendering,
not an auth token. It contains no user credentials and is safe to log.

MCI completeness

If Heimdall flags missed callers, it means you changed a function that's called from places not touched in this PR. Missed callers are often the cause of subtle bugs — the callee changed but the callers still expect the old behavior.

To get MCI caller analysis, your repo needs to be indexed. See Set Up Code Intelligence.

Test checklist

The test checklist is what Heimdall thinks should be tested given the diff. It's not a pass/fail gate — it's a prompt for your review. If a checklist item is already covered by an existing test, you can note that in a comment.

Using @heimdall

Mention @heimdall anywhere in a PR comment to ask a question about the code. Heimdall uses the surrounding diff as context.

@heimdall why is the token refreshed here instead of at the call site?

@heimdall is this change backward-compatible with the v1 API contract?

For questions about the whole PR rather than a specific line, mention Heimdall in a top-level review comment. It will fetch the entire diff before answering.

Enforcing your team's standards

Heimdall automatically enforces PRINCIPLE and DECISION atoms from your Momental workspace. If a PR violates a documented team standard, it appears in Concerns — not just a note.

To add a standard that Heimdall enforces:

await momental_node_create({
  statement: "All database queries must use the ORM. No raw SQL in application code.",
  nodeType: "PRINCIPLE",
  status: "ACTIVE"
});

The more standards you document, the more precisely Heimdall reviews against your team's actual engineering culture rather than generic best practices.

Troubleshooting

Heimdall didn't comment on my PR. Check that the GitHub App is installed on the repo's org (not just your personal account). Draft PRs are not reviewed — convert to a regular PR first.

The review seems generic. Heimdall's review quality improves with two inputs: (1) your MCI index — callers and callees give it structural context; (2) your team's PRINCIPLE/DECISION atoms — without them, Heimdall applies general best practices only.