Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

docs: add Archify review skill and streamline review guidance (#435)

tt-a1ibc8cdc854c80
diff --git a/.agents/skills/archify-review/SKILL.md b/.agents/skills/archify-review/SKILL.md
new file mode 100644
index 00000000..68b98baa
--- /dev/null
+++ b/.agents/skills/archify-review/SKILL.md
@@ -0,0 +1,20 @@
+---
+name: archify-review
+description: Review Archify issues, PRs, or code through value, cost, and impact to support evidence-based maintenance decisions. Use for issue triage, change reviews, and code quality assessments.
+---
+
+# Archify Review
+
+Judge whether a problem is worth addressing and an approach is worth maintaining over time.
+
+- **Value**: Identify the real problem, who benefits, how often it occurs, its consequences, and whether it is worth addressing now.
+- **Cost**: Consider implementation and verification effort, along with the future cost of understanding, changing, and maintaining the code. Prefer existing capabilities and keep the solution proportional to the problem.
+- **Impact**: Identify affected behavior and modules, consequences for users and future development, and whether the change improves maintainability or adds coupling and constraints.
+
+Consider maintainability, complexity, compatibility, performance, and other relevant concerns within these three dimensions, according to the specific problem.
+
+Ground judgments in evidence: verify the target revision and relevant facts, distinguish direct verification from existing evidence and assumptions, and choose checks that resolve the key uncertainties.
+
+Explain whether the work is worthwhile, the approach's cost and impact, any better alternatives, and unresolved questions that matter to the decision. Give reasons and scale the detail to the importance of each concern.
+
+For repository-specific review and contribution requirements, consult [REVIEWING.md](../../../REVIEWING.md) and [CONTRIBUTING.md](../../../CONTRIBUTING.md) as needed.
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
index e46a6cc3..4198288a 100644
--- a/.coderabbit.yaml
+++ b/.coderabbit.yaml
@@ -94,8 +94,8 @@ reviews:
maintainer scope decision. Narrow fixes may use a concrete reproduction;
small documentation or test corrections may use a rationale. Do not
require a PR to close every item of a tracking issue. Accept
- equivalent prose and explained Not applicable entries, not just exact
- headings or checked boxes. Warn once with the specific missing facts;
+ equivalent prose and omission of inapplicable template sections, not just
+ exact headings or checked boxes. Warn once with the specific missing facts;
read the latest description and maintainer decisions before repeating
a warning. Do not classify missing evidence as a confirmed runtime defect.
- name: Validation evidence
@@ -108,10 +108,11 @@ reviews:
coverage, and generated-artifact freshness when their inputs changed.
Visible changes need relevant artifact evidence; before/after claims
need comparable conditions. Automated/browser and perceptual results
- must be separate. Non-visual changes may explain Not applicable.
- Repository-only prose/policy and focused test fixes may use justified
- targeted checks under CONTRIBUTING.md; packaged Skill instructions and
- shared test infrastructure are not a documentation/test-only shortcut.
+ must be separate. Non-visual changes may omit visual evidence; changes
+ without generated-output impact may omit that section. Choose coverage
+ by actual behavior and callers under CONTRIBUTING.md. Relevant CI can
+ supply coverage without duplicating runs locally. Packaged Skill
+ instructions and shared test infrastructure may affect runtime behavior.
Reuse linked archive manifests, source comparisons, and freshness CI;
an excluded binary diff alone is not evidence of unrelated changes.
Distinguish author reports from observed final-head CI; skipped,
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 9ea43cef..ac999daa 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,21 +2,20 @@
## Problem and value
-Current-main trigger or rationale, intended outcome, approach, and linked issue/agreed scope:
+Current-main trigger or rationale, intended outcome, why the approach is worth maintaining, and linked issue/agreed scope:
## Stability impact
- Impact class and changed behavior/shared callers: <!-- CONTRIBUTING.md#choose-evidence-by-impact -->
- Existing behavior preserved / intended compatibility changes / failure behavior:
-- No unrelated changes: <!-- confirm or explain -->
## Tests run
-Comparison base and candidate head; applicable commands/results or evidence links. Explain omitted checks and identify reused evidence by its original revision. Follow CONTRIBUTING.md#choose-evidence-by-impact; required remote CI still applies.
+Comparison base and candidate head; applicable commands/results or evidence links. Identify reused evidence by its original revision and explain material coverage gaps. Follow CONTRIBUTING.md#choose-evidence-by-impact; required remote CI still applies.
## Visual evidence
-For non-visual changes, replace this section with "Not applicable" and why.
+Omit this section for non-visual changes.
- Evidence provided: <!-- screenshots, recordings, or reproducible steps; intended and unexpected differences -->
- Comparison conditions: <!-- same input, viewport, theme, preset, mode, zoom, page state -->
@@ -27,4 +26,4 @@ Report automated or browser evidence separately from perceptual review.
## Generated artifacts
-Regenerated files or linked build evidence; if none, explain why outputs remain fresh.
+Omit this section if generated outputs are unaffected. Otherwise list regenerated files or linked build evidence, and explain freshness of affected outputs left unchanged.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e3ed3162..84585f71 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,7 +20,7 @@ Use Draft for unresolved scope or early implementation feedback. At this stage,
Before requesting final review, explain:
-- The current-main trigger, intended outcome, and why the approach is worth maintaining.
+- The current-main trigger, intended outcome, and why the benefit justifies the implementation and ongoing maintenance cost.
- The changed behavior and shared callers, existing behavior that must remain stable, and any intended compatibility changes.
- The applicable checks, actual results, and reproducible evidence links.
@@ -30,19 +30,19 @@ Use [the PR template](.github/PULL_REQUEST_TEMPLATE.md); link existing receipts
| Impact | Typical change | Evidence to prepare |
| --- | --- | --- |
-| Text or review policy | Explanatory prose, links, contributor/reviewer procedure | Content, links, affected documentation checks; exercise changed procedure branches. No local renderer suite for repository-only prose. |
+| Text or review policy | Explanatory prose, links, contributor/reviewer procedure | Check content, links, and consistency with affected templates or automation. No local renderer suite for repository-only prose. |
| Local behavior | One CLI path, focused test correction | Reproduction or rationale, affected tests, and relevant failure/compatibility cases. |
| Shared behavior | Geometry, text measurement, shared Viewer, evidence or delivery helpers | Trace callers; identify affected modes and contracts; compare fixed representative inputs on base and candidate, including relevant historical failures. |
| Contract change | Schema, defaults, validation acceptance, Skill or authoring instructions | Agreed scope and explicit allowed/preserved behavior, plus local/shared evidence appropriate to the implementation. |
Skill instructions, authored examples, build inputs, and generated-site sources are behavioral inputs even when they look like documentation. Policy changes need process review; runtime evidence depends on whether they affect runtime inputs.
-During iteration, run the narrowest relevant checks. Before final review, run `npm test` from `archify/` for changes to runtime, schemas, packaged Skill/authoring behavior, generated content, or shared test infrastructure. Repository-only documentation and focused test-only changes may use targeted checks with an explanation. These local choices do not waive remote CI or branch-protection requirements.
+Start with focused checks for the affected behavior. Use the full `npm test` suite from `archify/` when shared behavior, broad changes, or findings require wider coverage. Final review needs sufficient evidence for the impact above; relevant CI results can supply that coverage without repeating the same run locally. Identify the revision and coverage of reused results, and explain material gaps. Required remote CI and branch protection still apply.
## Product and compatibility contracts
- Existing schema-v1 typed JSON remains valid unless a reviewed change explicitly introduces a breaking rule and migration path.
-- Explicit authored geometry such as `via`, named routes, channels, sides, and label placement remains authoritative unless the contract says otherwise. Preserve authored topology and intent.
+- Preserve authored topology and intent; explicit geometry remains authoritative unless the contract says otherwise. Consult the [authoring contract](archify/references/authoring-contract.md) and relevant renderer documentation for details.
- `standard` preserves broad compatibility. A new `showcase` failure must identify a real, repairable defect and avoid rejecting necessary routing.
- Agent-facing failures belong in `diagnostics[]`: use a stable `code`, precise `subject`, concrete `evidence`, and executable `supportedFixes`. Preserve non-zero CLI exits and machine-readable receipts for failed stages.
- A validation rule expressing taste should begin with evidence or a warning. Before making it a hard error, check legitimate obstacles, shared ports, explicit routes, nested boundaries, and existing examples.
@@ -62,7 +62,7 @@ Test through public behavior such as `render`, `validate`, `deliver`, `visual-ch
For geometry and layout changes, use the smallest redacted JSON reproduction, relevant checked-in examples, and frozen compatibility fixtures. Compare base and candidate with the same input and browser conditions. Identify intended changes and investigate unexpected ones; updating golden files alone does not establish visual or compatibility acceptance.
-A visual PR must provide enough evidence to evaluate whether the intended user value was achieved, using screenshots, recordings, or reproducible steps. Keep viewport, theme, preset, diagram mode, zoom, and page state comparable. Report automated or browser evidence separately from perceptual review. A non-visual pull request must write `Not applicable` in its Visual evidence section and explain why.
+A visual PR must provide enough evidence to evaluate whether the intended user value was achieved, using screenshots, recordings, or reproducible steps. Keep viewport, theme, preset, diagram mode, zoom, and page state comparable. Report automated or browser evidence separately from perceptual review. Non-visual changes may omit the Visual evidence section.
Static SVG/XML checks cannot establish browser layout, font settling, or interaction behavior. When the adaptive reader or Viewer layout changes, run the real browser test with Chrome available:
@@ -93,7 +93,7 @@ scripts/build-zip.sh /tmp/archify-contrib.zip
Canonical ZIP bytes require Node 22; the builder rejects other majors to avoid different zlib representations. Skill runtime, schema, renderer, and published Skill-instruction changes require checking ZIP freshness. Bundled example or Viewer changes normally require a Gallery rebuild.
-List regenerated files and explain why unchanged outputs remain fresh. Resolve generated conflicts by rebuilding from combined source. Keep unrelated generated output out of the diff.
+List regenerated files and explain freshness when an affected output is left unchanged. Changes that do not affect generated outputs may omit that PR section. Resolve generated conflicts by rebuilding from combined source. Keep unrelated generated output out of the diff.
Treat published versions as immutable. Ordinary feature PRs do not change versions, tags, or distribution identities unless release work is explicitly in scope.
@@ -105,46 +105,11 @@ On revision, summarize what changed since the reviewed head and which findings i
Showcase submissions should include the prompt, agent/client, model, Archify version, redacted JSON, artifact, receipts, and truthful visual-review status. Maintainers may request a smaller safe reproduction. Preserve attribution; showcase acceptance is not a controlled model-quality benchmark.
-## Automated review pilot
-
-The CodeRabbit GitHub App is enabled for this repository. The root
-[configuration](.coderabbit.yaml) requests automatic reviews of ready PRs and
-subsequent pushes. It uses this guide, REVIEWING.md, and the PR template for advisory scope and
-validation-evidence checks. Drafts are excluded. Missing evidence is a request
-for clarification, not proof of a code defect; explain a false positive in the PR.
-
-CodeRabbit does not replace required CI, browser/perceptual acceptance, or a
-maintainer's merge decision. Two warning checks cover contribution scope and
-validation evidence; overlapping built-in issue assessment is disabled. Authors
-can answer with evidence or explain why a request does not apply; maintainers
-settle disputed scope and acceptance requirements.
-
-Use these [review commands](https://docs.coderabbit.ai/reference/review-commands)
-instead of pushing an empty commit to retrigger the bot:
-
-| Situation | PR comment |
-| --- | --- |
-| Review new commits when automatic review did not run | `@coderabbitai review` |
-| Updated only the PR description, evidence links, or completed CI | `@coderabbitai run pre-merge checks` |
-| A fresh review of the entire PR is needed | `@coderabbitai full review` |
-| Several rapid revisions are in progress | `@coderabbitai pause`, then `@coderabbitai resume` when ready |
-
-Check the updated summary for results; a command acknowledgment is not completion.
-Treat its evidence assessment as a snapshot at the stated revision. After updating
-only the description or after CI completes, use the pre-merge command above to
-refresh stale results; editing the description is not proof that checks reran.
-Before repeating a bot request, read the latest evidence and identify the remaining
-gap. Reuse unaffected local results with their original revision and a reuse
-rationale; rerun checks whose evidence the new changes invalidate. Required remote
-checks must still pass on the final head.
-If fork CI needs approval, a maintainer must inspect the proposed workflow/code
-and handle the GitHub approval. Authors should link the waiting run and continue
-checks available to them; they are not expected to grant themselves CI access.
-
-Maintainers should assess the first
-5–10 reviewed PRs for useful findings, false positives, review time, and repeated
-evidence requests before expanding the pilot. Pause automatic reviews by setting
-`reviews.auto_review.enabled: false`; this does not change CI or branch protection.
+## Automated review
+
+CodeRabbit provides advisory feedback under the repository [configuration](.coderabbit.yaml). Answer with relevant evidence or explain why a finding does not apply. Missing evidence is an unresolved claim, not proof of a code defect. Maintainers settle disputed scope; required CI and the maintainer's merge decision remain separate.
+
+For retriggering or pausing reviews, use the official [review commands](https://docs.coderabbit.ai/reference/review-commands) and check the updated results. Bot assessments are snapshots at the stated revision; refresh stale checks after description or CI updates and read the latest evidence before repeating a request. Fork-CI approval requires a maintainer to inspect the proposed workflow/code changes; authors can link the waiting run.
## License
diff --git a/REVIEWING.md b/REVIEWING.md
index f206f534..128b9041 100644
--- a/REVIEWING.md
+++ b/REVIEWING.md
@@ -1,26 +1,22 @@
# Reviewing Archify changes
-Use this procedure for an initial PR review or a revised head, whether reviewing as a maintainer or an Agent. [Contributing](CONTRIBUTING.md) owns impact classes, compatibility contracts, and evidence requirements.
+Use this guide for initial and revised PR reviews. Judge the user value, implementation and ongoing maintenance cost, and impact on existing behavior. [Contributing](CONTRIBUTING.md#choose-evidence-by-impact) describes contribution and evidence requirements.
-## 1. Establish scope before detailed review
+## Understand the problem and approach
Record the current main/base and candidate head. Read the linked issue or agreed scope and check the current-main behavior where feasible. Separate the reported problem from the proposed implementation.
-Identify the user benefit, intended behavior changes, and preserved behavior. For a new default, schema field, or acceptance policy, settle the maintenance and compatibility decision before asking for implementation polish. Reuse decisions already made in the issue or authorized task.
+Identify who benefits and whether the approach is worth maintaining. Consider whether existing capabilities or a smaller change would solve the problem. For a new default, schema field, or acceptance policy, clarify the value and compatibility tradeoff early. Reuse decisions already made in the issue or authorized task.
-If scope remains undecided, report the specific decision needed and keep feedback at that stage. Narrow fixes can proceed on their reproduction without another planning exercise.
+If a decision is missing, explain how it affects the review and continue checks that do not depend on it. Narrow fixes can proceed on their reproduction without another planning exercise.
-## 2. Bound the investigation
+## Match investigation to impact
Check the author's [impact classification](CONTRIBUTING.md#choose-evidence-by-impact) against the changed paths and callers. Shared helpers, templates, and authoring instructions may affect more modes than the title suggests.
-Name the affected modes/contracts and the smallest evidence set that covers them. Include relevant historical failures and authored constraints. Explain any expansion beyond that set. Repository-only policy changes need consistency and process checks, not layout screenshots.
+Choose checks that resolve the important uncertainties, including relevant historical failures and authored constraints. Broaden the investigation when findings or coverage gaps warrant it. Repository-only policy changes need consistency checks, not layout screenshots.
-Use focused evidence during design and repair. Reserve broad integration checks and final artifact rebuilds for the settled change. Required remote CI and branch protection remain in force.
-
-## 3. Assess behavior and evidence
-
-Compare fixed inputs on the recorded base and candidate. Use existing renderers, layout receipts, tests, and browser tools:
+Use existing tests, receipts, and browser tools. For behavior comparisons, use fixed inputs on the recorded base and candidate:
- Account for changed and preserved topology, meaningful labels, explicit geometry, and relevant failure behavior.
- For affected visible behavior, inspect the intended differences and unexplained changes under comparable browser conditions. A pixel difference identifies a change; it does not judge its quality.
@@ -29,9 +25,9 @@ Compare fixed inputs on the recorded base and candidate. Use existing renderers,
Evidence should be sufficient for the affected contract. Avoid rebuilding an unchanged artifact or replaying unaffected checks merely to restate existing results.
-## 4. Give actionable feedback
+## Give actionable feedback
-Lead with the problem, value, and approach. Then report scope, evidence, and a clear disposition:
+Lead with whether the approach is worthwhile, then explain findings and a clear disposition:
- **Blocking defect:** trigger, impact, supporting evidence, and the behavior that must be corrected.
- **Required evidence or scope decision:** the unresolved claim, why it matters to acceptance, and the smallest check or decision that would settle it. An unverified risk is not a reproduced defect.
@@ -40,12 +36,10 @@ Lead with the problem, value, and approach. Then report scope, evidence, and a c
Consolidate scope and compatibility concerns in the first substantive review where possible. Explain any later blocker with newly found evidence, an overlooked acceptance requirement, or a new diff. Record unrelated issues separately instead of growing the PR's scope.
-Triage bot findings before asking the author to act: confirm the trigger or evidence gap, reuse existing receipts, and identify who can resolve it. Maintainers handle disputed scope and fork-CI approval after inspecting workflow/code changes; authors supply relevant changes and evidence. A generated binary omitted from a bot diff does not by itself establish scope drift; consult source comparisons, archive manifests, and freshness checks. Resolve duplicate or inapplicable requests with a short reason. Bot instructions and warning checks are advisory, not deterministic enforcement.
-
-A review disposition does not itself approve or merge on GitHub. Follow the authorized action and repository protection rules.
+Assess bot findings against the current diff and existing evidence before forwarding them. Explain duplicate or inapplicable findings; use the same standard of evidence as for your own feedback.
-## 5. Re-review the delta and finish
+## Re-review and finish
Compare against the last reviewed head, resolve outstanding findings, and inspect added changes. Check intervening main changes for effects on the earlier assessment. Expand review when those changes invalidate scope or evidence; do not treat an old pass as proof of new behavior.
-Completion requires the agreed outcome, preserved contracts, sufficient applicable evidence, and no unresolved acceptance blockers. Before an authorized merge, recheck the live head and required gates. Record remaining non-blocking limitations explicitly; arbitrary inputs outside the supported contract are not a demand for unlimited testing.
+Finish when the agreed outcome is delivered, relevant evidence is sufficient, and no acceptance blockers remain. Report non-blocking limitations. A review conclusion does not itself authorize a GitHub approval or merge; follow the authorized action and [final integration requirements](CONTRIBUTING.md#final-integration-and-follow-up).
diff --git a/archify/test/community-proof-intake.test.mjs b/archify/test/community-proof-intake.test.mjs
index 3369cead..1d09031b 100644
--- a/archify/test/community-proof-intake.test.mjs
+++ b/archify/test/community-proof-intake.test.mjs
@@ -111,7 +111,6 @@ test('contributor and pull-request guides keep proof changes reproducible and st
'Evidence provided:',
'Automated or browser checks:',
'Perceptual visual review: passed / failed / skipped / Not applicable',
- 'No unrelated changes',
]) {
assert.match(pullRequest, new RegExp(required), required);
}
@@ -119,7 +118,6 @@ test('contributor and pull-request guides keep proof changes reproducible and st
assert.match(contributing, /screenshots, recordings, or reproducible steps/i);
assert.match(contributing, /same input/i);
assert.match(contributing, /automated or browser evidence separately from perceptual review/i);
- assert.match(contributing, /non-visual pull request must write `Not applicable`/i);
assert.match(pullRequest, /screenshots, recordings, or reproducible steps/i);
assert.match(pullRequest, /automated or browser evidence separately from perceptual review/i);
assert.doesNotMatch(contributing, /must reach `passed` before final review or merge/i);