Using hints
Stuck on a scenario? Use hint. Inside an active scenario, each call reveals one more layer of guidance:
pgpg[scenario]> hint
How hints progress
Hints are progressive. The first hint points you in a direction; each subsequent call narrows things down until the mechanism is spelled out. They move roughly through three levels:
- Where to look — which subsystem or catalog to start from (for example, "check what is holding locks" or "look at the slow query's plan").
- What to look for — the specific signal that matters (a particular
pg_stat_activitystate, an index that is no longer being used, a setting that changed). - The mechanism — the actual cause and why it produces the symptoms in the brief.
Call hint again whenever you want the next level. You can stop as soon as you are unstuck — there is no penalty for reading further, and no requirement to.
pgpg[scenario]> hint
Look at what sessions are currently active and what they are waiting on.
pgpg[scenario]> hint
One session holds a lock that others are queued behind. Find the
blocker, not just the blocked.
pgpg[scenario]> hint
The blocker is an idle-in-transaction session that opened a lock
and never committed. Everything else is waiting on it.
Hints are fine to use
Hints are a normal part of working a scenario, not a last resort. Use them freely. They are designed to teach the diagnostic path, so leaning on them early is a reasonable way to learn a track you have not seen before.
Hints are tracked, not penalized
How many hints you took is recorded alongside your result so you can see how much help you needed on each scenario — useful for spotting which tracks to revisit. But hints do not block or reduce your score. The scorer only looks at the state of the database and your fix. You could read every hint and still earn a perfect score, or read none and miss the root cause.
This separation is deliberate:
- Hints help you find the answer.
- Scoring measures the answer.
The two never interfere with each other.
AI writes hints, never grades
Hint wording is generated by AI, so the phrasing is conversational and adapts to the scenario. That AI involvement is strictly limited to hints and explanations. It has no role in score:
| Concern | AI involved? |
|---|---|
| Hint wording | Yes |
| Explanations | Yes |
| Scoring | Never |
Scoring is fully deterministic and offline (see Scoring & postmortems). So while hints are flexible and phrased on the fly, your grade never depends on a model's judgment — only on whether the incident is actually resolved.