Back to Guides

Self-Healing Knowledge — A Team Guide

Guidelines · v1.13+

Compass closes its own knowledge gaps when teams play their part. This guide walks every team member through the loop: spot a gap → fix it where the knowledge really lives → Compass auto-reruns → the asker is notified. Every step lives on the Resolution Queue — the full-page surface in the sidebar (right under Dashboard). The remedy on each gap follows the team that owns the gap (and the teams you belong to): HR authors a Knowledge Base document; Application Support and Product Solution fix at source in the Zoho KB; every other team — Product Solution included — keeps a single Master FAQ. If you belong to more than one of these teams you'll see every option that applies to the gap (on a small ▾ menu). One action isn't team-bound: Insert Zoho KB link — pointing Compass at a published Zoho KB article that answers the question — is available to every Navigator, on every team. The faster you act on fresh gaps, the smarter Compass gets for the next person who asks.

1 The self-healing loop, at a glance
Every gap in the queue is a question Compass couldn't confidently answer. The loop below is how those gaps disappear — for good.
  1. Spot — A LOW or MEDIUM gap shows up in the Resolution Queue, scoped to your team. The dashboard's Needs attention ribbon nudges you when fresh ones land; click through to open the queue.
  2. Decide — Read the question. The row shows the remedy that fits the gap's owner team; when more than one path applies to you (e.g. you're in Product Solution and an engineering team), the extra options sit on a ▾ menu next to the main button.
  3. Fix at source — HR writes or edits a Knowledge Base document — Update Documentation (edit the doc that covers it) or Create Documentation (write a new one). Application Support and Product Solution fix in the Zoho KB — when the gap already retrieved an article they get Improve in Zoho KB (edit it at source). Insert Zoho KB link (paste a published article) is always available to every Navigator on every team, on any gap — because a gap is often closed by pointing Compass at an article that already exists, or one you just authored. Where both apply they sit together, with the extra one on the ⋮ / caret menu next to the row's primary button. Every other team (Product Solution too) edits its single Master FAQ — Update Master FAQ or Create Master FAQ the first time; if you belong to several Master-FAQ teams, a quick picker asks which team's FAQ the answer lands in.
  4. Compass auto-reruns — The moment your fix lands (a re-synced Zoho article, an inserted link, a saved Master FAQ), Compass re-asks the original question against the fresh knowledge. There's no manual "rerun" button to press.
  5. Done, automatically — When the rerun lands HIGH, Compass auto-resolves the row (it drops off the queue) and Lark-DMs the original asker with a link to their now-answered question. No manual "mark resolved" step.
Why it matters. A gap fixed today saves the same question being asked five more times this month. Self-healing is how the team scales its own knowledge without a dedicated content team.
Fix where the knowledge really lives. Application Support and Product Solution answers live in the Zoho KB, authored in Zoho and synced into Compass — so you edit them at source, in Zoho, and the fix flows back. Every team except Application Support and HR keeps one Master FAQ: a single quick-answer reference doc, not a sprawling library — Product Solution keeps its own too, so a product member gets both the Zoho KB and Master FAQ paths. HR is the exception — it's the one team that still authors full Knowledge Base documents directly in Compass (its content doesn't live in Zoho KB). The remedy is always tied to the gap's system of record; when your memberships give you more than one, the ▾ menu offers each.
2 Reading a gap row
Every chip on a gap row is a signal. The row below shows the full vocabulary at a glance.
Can a Razorpay refund reverse the loyalty points already awarded?
LOW Customer Loyalty MKMira K. · Sales 5× asked 21 days in gap
Confidence badge. LOW = Compass had to guess. MEDIUM = partial match. Both deserve a fix.
Owner team chip. The team responsible for the domain — it decides which remedy button shows. Only members of this team (or Captains) can act on the row.
Asker chip. Who asked it. They get the Lark DM automatically when the auto-rerun lifts the gap to HIGH.
Aging chips. 5× asked = repeat frequency. 21 days = red after 14 — the alarm bell.
3 Application Support & Product Solution — improve the Zoho KB article Navigator
For Application Support and Product Solution (and Captains), knowledge lives in the Zoho KB — articles authored in Zoho and synced into Compass. When a gap already retrieved a Zoho article, the row shows Improve in Zoho KB to edit it at source; after you've edited & published in Zoho, Re-sync & recheck — in the row's ⋮ menu — pulls your edit back in and re-asks the question.
Why does the terminal show "device not registered" after a firmware update?
LOW App Support RLRina L. · Support 4× asked 18 days in gap
This gap pulled 2 Zoho articles — which one did you edit?
📄 Registering a terminal after firmware updates
📄 Troubleshooting terminal connectivity
How the Zoho loop closes: 1) Improve in Zoho KB opens the article at source in Zoho — if the gap pulled several articles, a picker asks which one to edit. 2) You edit and publish in Zoho. 3) Back in Compass, Re-sync & recheck pulls that change in and re-runs the gap (if several articles, a picker asks which one you edited, so only that one is re-synced). 4) If it now lands HIGH, the gap auto-resolves and the asker is DM'd.
You don't have to press it. New and edited Zoho KB articles are auto-rechecked overnight by the nightly Zoho KB sync (askers DM'd then). Re-sync & recheck just does it immediately instead of waiting until morning.
4 Any team — insert a Zoho KB link (always available) Navigator
Insert Zoho KB link is always offered to every Navigator and Captain, on any team — on any gap, whether or not an article was already retrieved. If you know a published Zoho KB article that answers the question, you no longer wait for an Application Support or Product Solution member to paste it for you. Paste the article's portal link and Compass ingests it and rechecks this gap plus any other open gap the article now answers. When the row already has a primary button (e.g. Improve in Zoho KB or Master FAQ), Insert Zoho KB link sits on the caret ▾ menu beside it. Editing an existing article at source — Improve in Zoho KB and Re-sync & recheck — stays with Application Support, Product Solution and Captains; inserting a link only adds a published article to Compass, it never changes KB content.
How do I re-print a receipt from a closed shift on the mobile POS?
LOW App Support JKJamie K. · Support 3× asked 11 days in gap
Paste a published Zoho KB article link
https://support.xilnex.com/portal/en/kb/articles/reprint-receipt-closed-shift
How do I re-print a receipt from a closed shift on the mobile POS?
LOW App Support Rechecking…
Which link works. The public portal URL is enough — e.g. https://support.xilnex.com/portal/en/kb/articles/<slug>, including the ones whose slug ends in a long number (…/secondaryscreen-1784792367653). Copy it straight from the article's address bar. Compass fetches the article, ingests it into the Zoho KB set, and immediately rechecks the gap you were on.
The row shows a "Rechecking…" state while the background recheck runs. If the article answers the question, the gap auto-resolves and drops off the queue (and any other open gap the same article now answers resolves too). If that article didn't actually answer it, the Insert Zoho KB link button simply returns so you can try another.
Look-alike questions lock too. The same question often sits in the queue two or three times, asked in slightly different words. When Compass rechecks a gap, it rechecks those look-alikes against the same article — and every one of them switches to "Rechecking…" while that runs, so nobody wastes a second insert on a question that's already being handled. The list picks the change up on its own within a minute; you don't need to refresh. Whichever ones the article answers drop off together and their askers are notified.
5 Every other team — your Master FAQ Navigator
Every team except Application Support and HR keeps exactly one Master FAQ — a single quick-answer reference doc — including Product Solution (which also gets the Zoho KB path). The gap row shows Update Master FAQ if the team already has one, or Create Master FAQ the first time. If you belong to more than one Master-FAQ team, a quick picker asks which team's FAQ the answer lands in. Writing full Knowledge Base documents is still reserved for HR.
Which webhook fires when a stock-transfer is approved across regions?
LOW Engineering DPDev P. · Engineering 2× asked 6 days in gap
B I · 1.

Engineering — Master FAQ

A single reference of quick answers for the Engineering domain. Add a new Q&A entry for each gap you resolve.

ADD Which webhook fires when a stock-transfer is approved across regions? — the inventory.transfer.approved event, delivered once per destination region.

One doc, many answers. The Master FAQ is a living quick-reference — you append a new entry each time you close a gap, rather than spinning up a fresh document per question. On save, Compass re-indexes it and auto-reruns the gap.
6 ✨ Format with Compass — polish the Master FAQ before saving Navigator
Inside the Master FAQ editor, ✨ Format with Compass turns "I jotted down what I know" into a well-structured, retrieval-friendly entry. Hit it before saving — Compass rewrites your draft with proper headings, bullet points, and the consistent tone the rest of the FAQ uses. The retrieval pipeline rewards well-structured content with higher chunk match scores, which means future questions are more likely to land HIGH on the first try.
Your draft
razorpay refund + loyalty points

if refund happens before cycle close, points get reversed auto. if after cycle close, points stay but adjustment lands next cycle. partial refunds also reverse points proportional to amount refunded. need to make sure the cycle close date is configured in admin > loyalty settings otherwise the whole thing breaks
✨ After Format with Compass
# Razorpay refunds & loyalty point reversal

## Within the same loyalty cycle
Points awarded on the original purchase are **reversed automatically** when the Razorpay refund is processed before the cycle closes.

## After the cycle closes
Original points stay on the customer record. The adjustment is applied to the **next cycle** instead.

## Partial refunds
Points are reversed **proportional to the refunded amount**.

## Prerequisite
The cycle close date must be configured under **Admin → Loyalty Settings**. Missing this configuration breaks the reversal logic entirely.
What Format with Compass does:
  • Adds a clear H1 title and logical H2/H3 section headings.
  • Converts run-on paragraphs into scannable bullets and numbered lists.
  • Highlights key terms with bold and surfaces prerequisites.
  • Smooths tone — colleague-to-colleague, not chatbot-to-user.
  • Preserves your facts verbatim. It never invents details or removes information you wrote.
Always review the rewrite before saving. Compass formats well but it's not infallible — if a nuance got flattened, edit it back in. You stay the author of record.
7 The rerun is automatic — no button to press
There's no manual "rerun" step in the loop. The moment your fix lands — a re-synced Zoho article, an inserted link, or a saved Master FAQ — Compass re-asks the original question against the fresh knowledge on its own. If it lands HIGH, the gap auto-resolves and the asker is notified in the same moment.
Does the Stripe terminal sync mid-shift transactions if Wi-Fi drops?
MEDIUM App Support Rechecking…
Does the Stripe terminal sync mid-shift transactions if Wi-Fi drops? ✓ AUTO-RESOLVED · asker notified
HIGH App Support · verified just now
When the rerun lands HIGH: the row auto-resolves immediately — no manual "mark resolved" step. Compass Lark-DMs the original asker with a link to their now-answered question in the same moment, and the gap drops off your queue on the next refresh.
Overnight safety net. Even if you don't press Re-sync & recheck, every new or edited Zoho KB article is auto-rechecked by the nightly Zoho KB sync — askers are DM'd then. The manual re-sync and the Insert Zoho KB link flow simply do it immediately instead of waiting for the nightly run.
If a fix doesn't lift the gap, it stays on the queue. That's your signal the fix wasn't enough — sharpen the article/FAQ entry, or Reroute the gap if it really belongs to another team.
8 Which sources you can fix from Compass
Each team's remedy is tied to its system of record. The table below shows where your fix should land.
Source type Fixable from the queue? Auto-rerun reacts? Where the fix lands
document (HR) ✓ ✓ Knowledge Base document — Update Documentation (edit) or Create Documentation (new). HR only.
zoho-kb (App Support · Product Solution) ✓ ✓ Zoho KB — Insert Zoho KB link (always available, any team) plus Improve in Zoho KB (edit at source; App Support · Product Solution) when an article was retrieved
Master FAQ (every team except App Support & HR) ✓ ✓ Update / Create Master FAQ — right here in the editor (Product Solution keeps one too)
zoho-ticket (closed) ✗ ✗ Frozen — capture the answer in the Zoho KB / Master FAQ instead
gitlab-issue (closed) ✗ ✗ Frozen — capture the answer in the Zoho KB / Master FAQ instead
Why some sources are frozen. Zoho tickets and GitLab issues are point-in-time snapshots — editing them would rewrite history. If the answer changed, put the durable answer where the knowledge lives (the Zoho KB for Application Support & Product Solution, the Master FAQ for every other team) and let the closed source sit alongside as historical context.
9 Close the loop — the Lark DM to the asker
The moment the auto-rerun lifts the gap to HIGH, Compass auto-DMs the original asker on Lark with a link to their now-answered question. No manual step — the rerun is the closure. The team member who made the fix shows up as the resolver in the DM footer.
XC
Xilnex Compass
just now
✓ Your question now has an answer
"Can a Razorpay refund reverse the loyalty points already awarded?"
Yes — automatically, if the refund is processed within the same loyalty cycle. After the cycle closes, the original points stay and the adjustment lands in the next cycle. Partial refunds reverse points proportionally to the refunded amount.
Confidence: HIGH · was LOW · resolved by Wei T. (Customer Loyalty) just now
Where your "note to the asker" goes now: it lives in the fix itself. The DM reflects the fresh HIGH answer — so write the Zoho article or Master FAQ entry the way you'd want the asker to read it. Plain language, clear structure, a one-line summary at the top.
If the asker has no asked_by_open_id on file (legacy data, or they asked through an integration without a Lark identity), the DM is silently skipped — the fix still ships and the gap still auto-resolves, only the notification is missed. Admins can backfill via scripts/backfill_asker_open_id.py.
10 Habits that make the loop work
A few small habits that compound. Adopt these and your team's gap count trends to zero.
⚡ Triage yesterday's gaps first

The dashboard's Needs attention ribbon surfaces yesterday's questions specifically — they're freshest in askers' minds. Click through to the queue and fix while the context is warm.

📌 Fix at source, not on the side

Application Support & Product Solution edit the Zoho article; every team except App Support & HR appends to its Master FAQ. Putting the answer where the knowledge lives means it's there for the next asker — and the nightly sync keeps it fresh.

🔁 Always hit Format with Compass

A polished Master FAQ entry retrieves better. Two minutes of polish today saves the same question being asked five more times next month.

🎯 Aim for HIGH on the first fix

If the auto-rerun lands MEDIUM/LOW, the gap stays on the queue — your signal the fix wasn't enough. Sharpen the article or FAQ entry and let it recheck again; don't ship a half-fix.

🚨 Watch the red aging chips

Anything over 14 days unresolved is a chronic blind spot. These are the gaps costing your team the most in repeat questions.

↪ Reroute, don't ignore

If a gap is in another team's domain, open the row's ⋮ menu and pick Reroute to another team. It's not "their problem" until it lands in their Resolution Queue. While it waits, the row shows an ⏳ Awaiting approval pill and parks — the doc buttons step aside until the other team accepts or declines. The receiving team can also request deletion instead of sending it back, so if a question genuinely belongs to nobody an admin ends it rather than it ping-ponging between the two of you. You'll see a 🗑 Deletion requested pill appear next to the awaiting-approval one when that happens.

⚡ Re-sync instead of waiting overnight

Edited a Zoho article? Hit Re-sync & recheck to pull it in now. The nightly sync would catch it anyway, but the asker gets their answer today instead of tomorrow.

🪶 Keep FAQ entries focused

One question, one crisp answer per Master FAQ entry. Tight, well-headed entries retrieve better than sprawling walls of text.

🌱 Approve PD-group candidates

Compass also surfaces candidate answers from your team's Lark chats. Approving a good one is the lowest-effort way to grow your team's knowledge.

11 Who can do what
Compass uses three role tiers. Each unlocks more of the self-healing workflow.
Action Explorer 🔭 Navigator 🧭 Captain ⛵
Ask questions & see own questions ✓ ✓ ✓
See team's knowledge gaps — ✓ ✓
Create / Update Knowledge Base documentation (HR only) — ✓ (HR) ✓
Insert Zoho KB link (always available — any team) — ✓ ✓
Improve in Zoho KB (App Support · Product Solution) — ✓ ✓
Re-sync & recheck a Zoho article (App Support) — ✓ ✓
Update / Create the team Master FAQ (other teams) — ✓ ✓
Use Format with Compass (Master FAQ editor) — ✓ ✓
Reroute a gap to another team — ✓ ✓
Request deletion of a question (a Captain decides) — ✓ ✓
Approve / reject a deletion request — — ✓
Approve PD-group candidate docs — ✓ ✓
Queries Log (full system view) — — ✓
Why Explorers don't get action buttons. Explorers can see gaps so they understand the state of the team's knowledge — but fixing the Zoho KB, editing the Master FAQ, and rerouting are Navigator-or-Captain work. It keeps the cost-bearing actions (each fix triggers a Bedrock recheck; edits reshape retrieval) in the hands of members trained on the workflow.
12 Troubleshooting
Common snags and how to get past them.
I edited the Zoho article but nothing changed

Two things to check: did you publish the article in Zoho (a draft won't sync), and did you press Re-sync & recheck? Without the re-sync, Compass only picks the change up on the nightly Zoho KB sync.

The gap pulled several Zoho articles — which do I edit?

Both Improve in Zoho KB and Re-sync & recheck show a picker when more than one article was retrieved. Pick the one you actually edited so only that article is re-synced.

Insert Zoho KB link didn't resolve the gap

After the "Rechecking…" state finishes, the Insert Zoho KB link button returns — that article didn't answer the question at HIGH confidence. Try a more specific published article, or edit one at source and re-sync.

"Couldn't fetch that article from Zoho"

Compass found no published article behind that link. Check the article is published in Zoho (a draft or an internal-only article isn't readable), and that the link is a live support.xilnex.com portal URL you can open in a private browser window. Copying the URL straight from the article's address bar is the safest way to get it right.

My fix didn't lift the gap to HIGH

The gap stays on the queue when the auto-rerun still lands MEDIUM/LOW. Sharpen the Zoho article or Master FAQ entry — clearer structure, the exact terms the asker used, a one-line summary up top — and it will recheck again.

Conflict banner on save ("Master FAQ was changed")

Another teammate saved the team Master FAQ while you were editing. Hit Reload latest, merge your entry in, then save again. Your draft is preserved during reload.

Asker didn't receive the Lark DM

Most common cause: the asker doesn't have asked_by_open_id set (legacy data). The fix saved successfully, but the DM is silently skipped. Admins can backfill via scripts/backfill_asker_open_id.py.

Format with Compass changed a fact

Rare but possible. Review the diff (mentally compare to your draft) and edit any drift back in before saving. You're still the author of record.

My row shows the "wrong" button

The buttons are set by the gap's owner team plus the teams you belong to. Application Support & Product Solution rows show Improve in Zoho KB; every other team shows Update / Create Master FAQ. Insert Zoho KB link is on every row for every Navigator — look on the ▾ menu when another button is the row's primary — and if you belong to more than one of these teams, the extra options sit on the ▾ menu. If the gap really belongs to another domain, use Reroute.