nduckmink/arkon/arkon-review

arkon-review: Review Wiki Drafts

Editor/admin only. If list_pending_drafts returns a permission error, you don't have the required role.

Review Workflow

1. List pending drafts

list_pending_drafts()

Returns: draft ID, page slug, author, timestamp, note. Filter by workspace if needed:

list_pending_drafts(workspace_id="<uuid>")

2. Read a draft for review

review_draft(draft_id)

Returns side-by-side: proposed content and current page content (vN). Read both carefully.

You may also call read_wiki_page(slug) independently for fuller backlink context.

3. Decide

Approve as-is:

approve_draft(draft_id, reviewer_note="optional feedback to author")

Approve with your own edits (you want to tweak before publishing):

approve_draft(draft_id, edited_content_md="...", reviewer_note="approved with minor edits")

Request changes (the draft is on the right track but needs fixes; preferred over reject when iteration is realistic):

request_changes_on_draft(draft_id, reviewer_note="20+ char explanation — what to change and why")

The draft moves to needs_revision; author can resubmit_draft after addressing the note. The original draft stays — revision_round increments each round and prior submissions are snapshotted for diffing.

Reject (only when the proposal is fundamentally wrong — out of scope, factually broken, or duplicates an existing page):

reject_draft(draft_id, reviewer_note="clear reason why — required")

reviewer_note is required for both reject and request_changes — the author needs to understand what to fix. Prefer request_changes over reject unless the proposal cannot be salvaged.

Conflict on approve: if the page advanced past the draft's base_version while you were reviewing, approve_draft returns a conflict error. Re-call with allow_conflict=true to overwrite, or supply edited_content_md after merging the latest content yourself.

Self-approve is blocked: the server rejects approve attempts where the reviewer is also the author. Ask another editor.

Approving a create draft

When the draft was filed via propose_wiki_create, it has draft_kind: "create" and no page exists yet — approval materialises a new page using the contributor's suggested metadata. The reviewer may override before commit via the REST endpoint body (in the portal UI):

• final_slug — adjust the URL slug
• final_title — adjust the display title
• final_page_type — change page_type
• final_knowledge_type_slugs — fix the taxonomy tags (matters for RBAC)

Why adjust metadata? RBAC visibility is driven by knowledge_type_slugs; slug shapes the URL forever; page_type affects how the page renders in the index. Contributors are often not aware of the conventions — quietly fixing these at approve is cheaper than asking them to resubmit.

If the slug already exists in the target scope, approval returns 409 slug_conflict — override final_slug or send the draft back with a request_changes note explaining why.

AI pre-review signals

Every draft carries an AI verdict (ai_check_status plus a list of checks):

• `passed` — no warnings. Most likely safe to approve after a quick read.
• `warned` — soft issues: broken wikilinks, possible duplicates, tone

drift, scope-fit doubts. Read them; some are noise, some matter.

• `failed` — at least one PII / secret regex match. Read each match

carefully. The contributor may have meant to include it (look for a <!-- pii-allow: ... --> marker above the match). If not, that's a request_changes situation.

The AI never blocks approval — it's a checklist, not a gate. Trust your own judgment.

Review Checklist

Before approving, verify:

• [ ] Content is factually consistent with other wiki pages (check backlinks if unsure)
• [ ] No sensitive data (PII, credentials, confidential figures) exposed
• [ ] Wikilinks [[slug]] point to real pages, not broken references
• [ ] Tone matches the KB style (factual, neutral, encyclopedic)
• [ ] The change note from the author makes the intent clear

Batch Review

For multiple drafts:

1. list_pending_drafts() — get the full queue.
2. Group by page type or workspace if useful.
3. review_draft each one in order.
4. Approve/reject individually — do not bulk approve without reading each.

Always confirm with the user before approving a batch of more than 3 drafts in one go.

Notes

• Approving a draft writes directly to the wiki page and creates a revision in history.
• Rejected drafts stay in the system with status: rejected — they are not deleted.
• You cannot approve your own drafts (the server enforces this).