Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
docs: clarify visual evidence requirements (#300)
Friend A60080fbbe531
diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.ymlindex 5ef8add0..ec1deab6 100644--- a/.github/ISSUE_TEMPLATE/bug-report.yml+++ b/.github/ISSUE_TEMPLATE/bug-report.yml@@ -86,11 +86,13 @@ body:validations:required: true- - type: textarea- id: screenshot+ - type: upload+ id: visual_evidenceattributes:- label: Optional final-artifact screenshot- description: Drag in a screenshot when the problem is visual. Mark the defect if it is subtle.+ label: Supporting visual evidence+ description: When it helps reviewers evaluate a visual problem, upload screenshots or recordings and mark subtle defects. Reproducible steps above may be enough when media would not add useful context.+ validations:+ required: false- type: textareaid: environmentdiff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex 92e0a057..e0d5ad09 100644--- a/.github/PULL_REQUEST_TEMPLATE.md+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -20,7 +20,14 @@ List exact commands and results. Do not write only “tests pass.”## Visual evidence-For visible changes, attach before/after final-artifact screenshots and state whether visual review passed, failed, or was skipped. Write “Not applicable” for non-visual changes.+Provide enough evidence to evaluate whether the intended user value was achieved. Use screenshots, recordings, or reproducible steps as appropriate to the affected behavior. For non-visual changes, write “Not applicable” and briefly explain why.++- Evidence provided:+- Comparison conditions, when applicable (input, viewport, theme, preset, diagram mode, zoom, and page state):+- Automated or browser checks:+- Perceptual visual review: passed / failed / skipped / Not applicable++When presenting a before/after comparison, keep its conditions genuinely comparable. Report automated or browser evidence separately from perceptual review; an automated check does not establish a perceptual pass.## Generated artifactsdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 7f098abe..687146a0 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -124,9 +124,11 @@ A useful bug report or fix contains:2. The smallest redacted typed JSON that still reproduces the failure.3. The complete machine-readable validation receipt or exact error.4. Expected versus actual behavior.-5. A final-artifact screenshot only when the problem is visual.+5. Enough visual evidence to evaluate the problem when it is visual. Use screenshots, recordings, or reproducible steps as appropriate, mark subtle defects when useful, and describe the expected visual result. Media is not required when it would not add useful context.-Do not replace deterministic evidence with a screenshot. For visual defects, keep both the validator result and final rendered evidence.+Do not replace deterministic evidence with visual evidence. For visual defects, keep both the validator result and final rendered evidence.++A pull request that changes the final diagram, Viewer, or public page appearance or interaction must provide enough evidence to evaluate whether the intended user value was achieved. Use screenshots, recordings, or reproducible steps as appropriate to the affected behavior. When presenting a before/after comparison, generate both states from the same input and keep the viewport, theme, preset, diagram mode, zoom, and page state comparable. Report automated or browser evidence separately from perceptual review; an automated check does not establish a perceptual pass. A non-visual pull request must write `Not applicable` in its Visual evidence section and briefly explain why. Remove sensitive data from every submitted artifact.## Community showcase submissions@@ -140,7 +142,8 @@ Maintainers may ask for a smaller source file, rerun validation, or decline a ca- Complete `.github/PULL_REQUEST_TEMPLATE.md` with exact commands and numeric results; do not write only “tests pass.”- Add or update a regression test for behavioral changes.- Confirm existing public examples and compatibility fixtures still behave as intended.-- State `visual review: passed`, `failed`, or `skipped` truthfully for visible changes.+- Provide enough evidence to evaluate the intended user value, using screenshots, recordings, or reproducible steps as appropriate, or explain why visual evidence is not applicable.+- Report automated or browser evidence separately from perceptual review, and state each result truthfully.- Confirm remote CI actually ran on the current head. Local green checks do not mean GitHub CI passed, and zero checks is not green.- Remove unrelated files, debug output, local paths, generated noise, and sensitive data from the diff.diff --git a/archify/test/community-proof-intake.test.mjs b/archify/test/community-proof-intake.test.mjsindex 5557da93..3369cead 100644--- a/archify/test/community-proof-intake.test.mjs+++ b/archify/test/community-proof-intake.test.mjs@@ -53,15 +53,26 @@ test('bug intake captures a minimal deterministic reproduction before visual dia'id: validation_receipt','id: expected','id: actual',+ 'id: visual_evidence','id: environment','id: sensitive_data',]) {assert.match(template, new RegExp(field), field);}assert.ok(- template.indexOf('id: validation_receipt') < template.indexOf('id: screenshot'),- 'deterministic evidence should be requested before optional visual evidence',+ template.indexOf('id: validation_receipt') < template.indexOf('id: visual_evidence'),+ 'deterministic evidence should be requested before visual evidence',);+ const evidenceBlock = template.slice(+ template.indexOf('id: visual_evidence'),+ template.indexOf('id: environment'),+ );+ assert.match(template, /type: upload\s+id: visual_evidence/);+ assert.match(evidenceBlock, /required:\s*false/);+ assert.match(evidenceBlock, /screenshots or recordings/i);+ assert.match(evidenceBlock, /Reproducible steps above may be enough/i);+ assert.doesNotMatch(evidenceBlock, /Required for visual problems/i);+ assert.doesNotMatch(evidenceBlock, /accept:/);});test('contributor and pull-request guides keep proof changes reproducible and stability-first', () => {@@ -97,8 +108,20 @@ test('contributor and pull-request guides keep proof changes reproducible and st'Tests run','Generated artifacts','Visual evidence',+ 'Evidence provided:',+ 'Automated or browser checks:',+ 'Perceptual visual review: passed / failed / skipped / Not applicable','No unrelated changes',]) {assert.match(pullRequest, new RegExp(required), required);}+ assert.match(contributing, /enough evidence to evaluate whether the intended user value was achieved/i);+ 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);+ assert.doesNotMatch(pullRequest, /must reach `passed` before final review or merge/i);});