Review Brief Skill

Workflow

Step 0: Discover Brief

If brief_path is not provided:

1. Search for *-brief.md files in the current directory and cogni-visual/ subdirectory
2. If multiple briefs found, present them via AskUserQuestion and let the user choose
3. If one brief found, confirm it with the user

Step 1: Parse Brief & Detect Type

Read the brief file. Extract:

• YAML frontmatter (type, version, arc_type, arc_id, theme, language, title)
• Brief body content

Detect brief_type from:

1. Explicit parameter (if provided)
2. Frontmatter type: field
3. Filename pattern: presentation-brief.md → slides, web-brief.md → web, storyboard-brief.md → storyboard, infographic-brief.md → infographic

Step 2: Discover Source Narrative

If source_narrative is not provided, look for it:

1. Check brief frontmatter for source_path or narrative_path
2. Search sibling directories for narrative files (files with arc_id in frontmatter)
3. If not found, proceed without it (skip completeness checks, note the gap)

Step 3: Launch Review

Launch the brief-review-assessor agent with:

• brief_path: the brief file
• brief_type: detected type
• source_narrative: if found
• audience_context: if provided
• round: 1

Step 4: Present Results

Parse the assessor's JSON response and present a formatted summary:

## Brief Review: {title}

**Verdict: {ACCEPT|REVISE|REJECT}** (Score: {overall_score}/100, Round {round})

### Perspective Scores
| Perspective | Score | Status |
|-------------|-------|--------|
| {name} | {score} | {pass|warn|fail} |
| {name} | {score} | {pass|warn|fail} |
| {name} | {score} | {pass|warn|fail} |

### Improvements Needed
**CRITICAL:**
- {description} (flagged by: {stakeholders})

**HIGH:**
- {description} (flagged by: {stakeholders})

**OPTIONAL:**
- {description} (flagged by: {stakeholders})

### Revision Guidance
{synthesis.revision_guidance}

Write the full JSON verdict to {brief_name}.review.json alongside the brief file.

Step 5: Handle Verdict

On accept: Report success. The brief is ready for rendering.

On revise (auto_improve=true):

1. Apply CRITICAL improvements first, then HIGH improvements
2. For each improvement, edit the brief content surgically — change the specific section, headline, layout type, or CTA referenced in the recommendation
3. Re-validate structural integrity (check YAML frontmatter is valid, section counts are consistent, no broken references)
4. Re-launch the assessor (round 2)
5. If round 2 accepts or scores 70+ with no CRITICAL issues: write the improved brief
6. If round 2 still has issues: present remaining issues to user, write brief with .review.json noting unresolved items

On revise (auto_improve=false): Report the findings and let the user decide. Offer:

• "Would you like me to apply the improvements automatically?"
• "Would you like to edit the brief manually and re-run the review?"

On reject: Surface to user via AskUserQuestion. Rejection means fundamental issues that need human judgment — the skill should not auto-fix rejections.

Step 6: Write Review Artifact

Write the review verdict JSON to {brief_stem}.review.json in the same directory as the brief.

If improvements were applied, also note:

{
  "improvements_applied": 3,
  "improvements_skipped": 1,
  "rounds_completed": 2,
  "final_verdict": "accept",
  "final_score": 87
}

Integration with Story-to-X Skills

This skill can be invoked standalone, but the story-to-X skills also integrate the brief-review-assessor agent directly into their workflow (between validation and write steps). When invoked from a story-to-X skill, the review is gated by the stakeholder_review parameter and follows the same assess → improve → re-assess loop.

The standalone skill exists for:

• Reviewing briefs after manual edits
• Reviewing briefs produced in earlier sessions
• Reviewing briefs from other sources
• Running a second review after rendering feedback suggests brief-level issues