ai-for-dummies/submitted-skills/Marcos Silva/skills/page-reviewer/SKILL.md

name, description

name	description
page-reviewer	Audit a Confluence-ready body before it is posted or updated. Use as the last gate before confluence_create_page_from_file or confluence_update_page_from_file; do not post a page that has not been through this skill.

Page reviewer

A Confluence page is hard to walk back once it's live: watchers, reactions, and links accumulate, and minorEdit=true will not save you from a body that embarrasses the team. Run this skill before every create or update.

The reviewer reads the draft and the page-context, and returns one of three verdicts:

• PASS — body is ready, post it
• REVISE — specific, line-anchored changes are required before posting
• BLOCK — something about the draft cannot be fixed locally (wrong space, wrong parent, scope creep, secret leak) — escalate

The reviewer never edits the draft. It returns a checklist; the human or the confluence-page skill applies the changes.

Hard rules

• No body that contains secrets, tokens, session cookies, customer PII, or internal hostnames (*.netcracker.com internal suffixes are fine in links; IPs, hostnames and ports from runbooks are not). The reviewer blocks on first match.
• No body that references the local mirror path (~/Netcracker/Projects/NDO/knowledge/...). Use the public BASS URL.
• No body larger than 300 lines without a one-line reason in the draft header. Pages drift; reviewers and readers both lose when they do.
• No body whose title collides with an existing page under the same parent — see step 2 of the workflow.
• No unrendered macros — every {plantuml}, {code}, {info}, {note}, {warning} block must be in its proper storage form (see confluence-page/references/macros.md). The reviewer rejects raw wiki markup and raw Markdown inside storage bodies.

Workflow

1. Identify the page. Title, parent, space key, target id (for update).
2. Collision check. If creating:
   • mcp__atlassian.confluence_search(cql="space=<SPACE> AND title~\"<title>\"")
   • If a page already exists under the same parent, return BLOCK with "title collision — pick a more specific title or update the existing page instead".
3. Pull upstream context. If updating, fetch the current body with mcp__atlassian.confluence_get_page_content(pageId) and diff against the draft. Flag any section that was renamed or deleted upstream and carried forward in the draft without intent.
4. Lint the body. For each of the checks below, return a line number and a short rationale. See references/checks.md for the full list and severity table.
5. Slop pass. Run the unslop skill on the body. If unslop returns more than 5 fixes for a page under 100 lines, or more than 10 for any page, return REVISE — the author should reread, not the agent.
6. Diagram sanity. For every {plantuml} block, parse to a .puml temp file and run plantuml -checkonly -syntax if plantuml is on $PATH. If the tool is missing, skip the parse and warn — do not block on a missing optional tool.
7. Render verdict.

Verdict shape

PASS:
  - ready to post; no blocking issues
  - (optional) minor notes for the author

REVISE:
  - L<line>: <rule> — <one-line fix>
  - L<line>: <rule> — <one-line fix>
  - ...
  - estimated fix effort: <s|m|l>

BLOCK:
  - <rule>: <what's wrong, what to do instead>
  - <rule>: ...

The verdict is the only thing the calling skill should consume. Everything else (diff, lint output, slop report) goes to stderr / a side file for the human.

What the reviewer does NOT do

• Edit the draft. The author or the confluence-page skill applies fixes. Reviewer that also edits is hard to audit.
• Post anything. The reviewer never calls a write MCP tool.
• Judge voice. Use unslop for that. The reviewer enforces structure, safety, and rendering correctness; unslop enforces voice.
• Approve secrets in test data. Even "obvious" test fixtures get blocked. If you need sample data with realistic-looking identifiers, generate them with the project's standard placeholder vocabulary.

Severity table

Severity	Returns	Examples
Blocker	BLOCK	secret leak, wrong parent, wrong space, title collision, raw wiki markup in storage body
Major	REVISE	unrendered macro, broken internal link, image without alt text, slop cluster
Minor	PASS (with note)	inconsistent heading levels, missing one-line summary, sub-optimal anchor text

Full rule list: references/checks.md.

Related

Skill	Role
confluence-page	Calls the reviewer before every create/update
unslop	Voice-level pass; the reviewer delegates voice to it
diagram-plantuml	Owns PlantUML syntax; the reviewer delegates diagram parsing to it