Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions skills/wgo/references/common/reviewer-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,17 @@ workspace without explicit authorization.

## Decision Usefulness

For every Key Findings row, assign severity, effort, and optional taxonomy from
the evidence. Severity is consequence-based: `Critical` for exploitable
security exposure, data-loss risk, or production-failure conditions; `High` for
material risk likely in normal operation; `Medium` for meaningful contained or
near-term-unlikely risk; and `Low` for minor cleanup or hardening. Effort is
the smallest responsible next move: `S` for a local/single-owner proof or
change, `M` for coordinated multi-file/process work, and `L` for broad
architecture, governance, migration, or external-party work. Use taxonomy only
when it is a direct fit, such as CWE, ASVS, SLSA, OSPS, or a project-defined
control label; otherwise write `none`.

Derive zero or more decision insights from the reviewed evidence. An insight
names the decision it changes, the causal relationship or conflict behind it,
the consequence of a wrong choice, and the smallest next proof or action. A
Expand Down
16 changes: 9 additions & 7 deletions skills/wgo/references/common/synthesis.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,13 +35,15 @@ unverifiable conclusions. Do not call a finding introduced unless dated
evidence establishes that timing.

Promote a reviewer finding into a synthesis insight only when it changes a
decision, priority, sequence, claim, or stop condition. Preserve all independent
material insights; combine only those that change the same decision. Do not set
a target number or promote a fact merely to fill one. In the executive summary's
`Material Risks, Unknowns, And Decisions` section, add a `### Decision-Useful
Conclusions` subsection when one or more material insights exist. Route each to
the audience that must decide or act, with linked evidence and the smallest next
move.
decision, priority, sequence, claim, or stop condition. Preserve the finding's
severity, effort, and taxonomy when carrying it into synthesis or technical
lead notes; do not collapse severity into open-item priority. Preserve all
independent material insights; combine only those that change the same
decision. Do not set a target number or promote a fact merely to fill one. In
the executive summary's `Material Risks, Unknowns, And Decisions` section, add
a `### Decision-Useful Conclusions` subsection when one or more material
insights exist. Route each to the audience that must decide or act, with linked
evidence and the smallest next move.

Then separate the remaining material open items into `### Decisions Now`,
`### Evidence Needed`, and `### Implementation Corrections`, using the canonical
Expand Down
2 changes: 2 additions & 0 deletions skills/wgo/references/templates/report-templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ lane; do not present all P1 items as one queue.

## Current Technical Position
## Architecture, Operations, Quality, And Security Findings
Preserve reviewer severity, effort, and taxonomy for material findings so
technical readers can distinguish impact from fix size and framework mapping.
## Safe Evolution Priorities
## Traceability And Limits
```
10 changes: 8 additions & 2 deletions skills/wgo/references/templates/reviewer-report-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,14 @@ State what was examined and only material gaps. Link an open item or source-acce

## Key Findings

| Finding | Evidence links | Confidence and limitation | Consequence |
|---|---|---|---|
| Finding | Severity | Effort | Evidence links | Confidence and limitation | Consequence | Taxonomy |
|---|---|---|---|---|---|---|

Severity is `Critical`, `High`, `Medium`, or `Low`, based on evidenced
consequence. Effort is `S`, `M`, or `L`, based on the smallest responsible next
proof or correction. Use `Taxonomy` only when a stable label such as CWE, ASVS,
SLSA, OSPS, or project-defined control vocabulary directly fits; otherwise
write `none`.

## Mandate-Relevant Strengths

Expand Down
20 changes: 19 additions & 1 deletion tests/test_skill_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -452,6 +452,7 @@ def test_decision_insights_are_qualitative_not_a_quota(self) -> None:
reviewer = (SKILL / "references/common/reviewer-audit.md").read_text(encoding="utf-8")
quality = (SKILL / "references/common/artifact-quality-review.md").read_text(encoding="utf-8")
synthesis = (SKILL / "references/common/synthesis.md").read_text(encoding="utf-8")
normalized_synthesis = " ".join(synthesis.split())
reviewer_template = (
SKILL / "references/templates/reviewer-report-template.md"
).read_text(encoding="utf-8")
Expand All @@ -462,22 +463,39 @@ def test_decision_insights_are_qualitative_not_a_quota(self) -> None:
self.assertIn("Derive zero or more decision insights", reviewer)
self.assertIn("Do not create an insight to fill a count", reviewer)
self.assertIn("Do not require or cap candidates", quality)
self.assertIn("Do not set\na target number", synthesis)
self.assertIn("Do not set a target number", normalized_synthesis)
self.assertIn("### Decision Insights", reviewer_template)
self.assertIn("### Decision-Useful Conclusions", synthesis_templates)

def test_open_items_are_prioritized_within_their_next_move(self) -> None:
reviewer = (SKILL / "references/common/reviewer-audit.md").read_text(encoding="utf-8")
synthesis = (SKILL / "references/common/synthesis.md").read_text(encoding="utf-8")
controls = (SKILL / "references/templates/control-templates.md").read_text(encoding="utf-8")
reports = (
SKILL / "references/templates/reviewer-report-template.md"
).read_text(encoding="utf-8")
templates = (SKILL / "references/templates/report-templates.md").read_text(encoding="utf-8")
normalized_reviewer = " ".join(reviewer.split())
normalized_reports = " ".join(reports.split())
normalized_synthesis = " ".join(synthesis.split())

self.assertIn("Type` as the next-move lane", reviewer)
self.assertIn("Priority orders work within its lane", reviewer)
self.assertIn("| Finding | Severity | Effort | Evidence links | Confidence and limitation | Consequence | Taxonomy |", reports)
self.assertIn("Severity is `Critical`, `High`, `Medium`, or `Low`", reports)
self.assertIn("Effort is `S`, `M`, or `L`", reports)
self.assertIn("CWE, ASVS, SLSA, OSPS", normalized_reports)
self.assertIn("For every Key Findings row", normalized_reviewer)
self.assertIn("Severity is consequence-based", normalized_reviewer)
self.assertIn("Effort is the smallest responsible next move", normalized_reviewer)
self.assertIn("Use taxonomy only when it is a direct fit", normalized_reviewer)
self.assertIn("severity, effort, and taxonomy", normalized_synthesis)
self.assertIn("do not collapse severity into open-item priority", normalized_synthesis)
self.assertIn("### Decisions Now", synthesis)
self.assertIn("### Evidence Needed", synthesis)
self.assertIn("### Implementation Corrections", synthesis)
self.assertIn("Priority orders items within their type", controls)
self.assertIn("Preserve reviewer severity, effort, and taxonomy", templates)
self.assertIn("do not present all P1 items as one queue", templates)

def test_same_root_resume_preserves_open_item_and_decision_ids(self) -> None:
Expand Down