# Arkon Review

> Arkon Review is an Agent Skill for productivity published in the nduckmink/arkon repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Review, approve, request changes on, or reject pending wiki edit drafts in Arkon. Requires editor or admin role. Triggers on: review drafts, pending reviews, check draft queue, approve draft, reject draft, request changes, send draft back, review wiki changes.

- Skill name: `arkon-review`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/nduckmink/arkon/blob/HEAD/skills/arkon-review/SKILL.md
- Repository: nduckmink/arkon (1,060 GitHub stars when collected)

## SKILL.md

# 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).

---

Source: https://www.openparable.com/skill/productivity/arkon-review (OpenParable). Cite the canonical URL above.
