Marcos Silva
114 lines
4.9 KiB
Markdown
114 lines
4.9 KiB
Markdown
---
|
|
name: page-reviewer
|
|
description: 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](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](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 |
|