Troubleshooting and FAQ

The pull request does not appear

1. Confirm the repository is included in the GitHub App installation.
2. Open Settings → GitHub and check that the installation belongs to the correct Fullbeam team.
3. Update the pull request or start a repository backfill.
4. In GitHub, inspect recent App webhook deliveries and confirm that pull_request events receive a successful response.

Analysis is still running

Analysis runs after the webhook is accepted. Large diffs or provider retries can take longer. If the state becomes failed, use the displayed failure category and run ID instead of pushing empty commits.

Analysis failed

• Provider: the AI provider did not complete the request. Check credentials and provider availability, then retry.
• Validation: the result did not satisfy Fullbeam's chapter, atom, or citation contract. Retry once; report persistent failures with the run ID.
• Budget: the configured analysis budget was reached.
• Fetch or GitHub: Fullbeam could not read the required revision. Check repository access and GitHub availability.

Earlier review marks remain available when a newer analysis fails.

The GitHub comment is missing

Confirm that the GitHub App can write pull-request issue comments and that the repository is still selected. The story remains available from the Fullbeam check and Pull Requests inbox.

Agent telemetry is missing

Run fullbeam doctor --json. Confirm the device is authenticated, the Git remote matches a connected repository, and the agent integration is enabled. Missing telemetry does not invalidate a diff-based PR Story.

A Harness Pack is out of date or drifted

Run fullbeam harness status and fullbeam harness drift with the correct provider. Use sync to apply the assigned revision or rollback to restore the previous installed revision.

Frequently asked questions

Do I need to connect a coding agent?

No. The GitHub App is enough for PR Stories. Agent integration adds richer build context.

Does Fullbeam work only with agent-written PRs?

No. It can organize human-written, agent-written, and mixed pull requests.

Does Fullbeam approve or reject PRs?

No. Fullbeam organizes evidence and preserves progress. Final review actions remain in GitHub.

Will Fullbeam add a new comment after every push?

No. It maintains one summary comment and updates its story and chapter links.

Why can one chapter contain several files?

Chapters represent outcomes or decisions. Several files can work together to produce one behavior.

Why is a detail missing from the explanation?

The story intentionally omits routine and obvious details. The complete associated diff remains beside the chapter.

Can Fullbeam prove that a prompt or skill caused a better result?

No. It reports observed associations with sample sizes and source coverage, not causal proof.

What happens after the PR changes?

Fullbeam compares the new revision with your checkpoint. Unchanged chapters keep continuity; affected chapters require another look.

Can someone use a copied link without repository access?

No. Fullbeam checks authentication and workspace entitlements when the story loads.

Can we select only some repositories?

Yes. Choose selected repositories during installation and change the selection later in GitHub.

What should I include in a support report?

Include the repository, pull-request number, Fullbeam run ID, and failure category. Never include secrets, device credentials, or private prompt content.