qmu/analyze-viewpoint

Analyze Viewpoint

Generic framework for analyzing a repository from a specific architectural viewpoint. Viewpoint definitions (prompts, diagram types, sections) are provided by the caller.

Gather Context

Run the bundled script to collect viewpoint-specific information:

bash ${CLAUDE_PLUGIN_ROOT}/skills/analyze-viewpoint/scripts/gather.sh <viewpoint-slug> [base-branch]

Default base branch is main.

Check for Overrides

Run the override reader to check for user-defined viewpoint customizations:

bash ${CLAUDE_PLUGIN_ROOT}/skills/analyze-viewpoint/scripts/read-overrides.sh

If overrides exist, merge them with the viewpoint definition received from the caller.

Output Template

Each viewpoint produces a spec document following this structure:

---
title: <Viewpoint Name> Viewpoint
description: <viewpoint description>
category: developer
modified_at: <ISO 8601 datetime>
commit_hash: <from context>
---

# <Viewpoint Name> Viewpoint

<introductory paragraph explaining the viewpoint's scope>

## <Section 1 from viewpoint definition>

<content with analysis>

## <Section 2 from viewpoint definition>

<content with analysis>

...

<!-- Diagrams go inline within content sections above, not in a separate section -->

## Assumptions

<clearly mark inferred vs explicit knowledge>

Diagram Placement Policy

Diagrams are inline within content sections, not in a separate "Diagram" section:

• Place each diagram immediately after the prose it illustrates
• Give each diagram a descriptive subsection heading (e.g., "### Ticket Lifecycle Flow")
• Never title a diagram section simply "Diagram"
• Use at least 2 diagrams per spec, with different Mermaid types where appropriate
• The viewpoint definition suggests diagram types; use them as starting points

Mermaid Node Label Quoting (REQUIRED)

When generating Mermaid diagrams, MUST quote labels containing special characters (/, {, }, [, ]):

• A[/command] -- WRONG, causes GitHub lexical error
• A["/command"] -- CORRECT
• B{Decision?} -- acceptable (no special chars inside braces)
• C["path/to/file"] -- CORRECT for paths with slashes

This is especially common for slash-command labels like /ticket, /drive, /scan, /report.

Assumption Section Rules

Every viewpoint spec must include an Assumptions section at the end:

• Explicit: Facts directly observed in code, configuration, or documentation
• Inferred: Conclusions drawn from patterns, naming conventions, or structural analysis
• Prefix each assumption with [Explicit] or [Inferred]
• When the codebase has no explicit information for a topic, state what was inferred and why

Comprehensiveness Policy

• Document everything observable in the codebase
• Do not judge any aspect as "not worth documenting"
• Small details and edge cases are valuable
• When in doubt, include rather than exclude

Inference Baseline Guidelines

When the codebase provides no explicit information:

• Analyze naming conventions, file structure, and patterns
• State conclusions as inferences, not facts
• Provide the reasoning chain that led to the inference
• Flag areas where explicit documentation would improve clarity

Cross-Viewpoint References

Viewpoint specs should reference each other when topics overlap:

• Use relative links: See [Component Viewpoint](component.md) for module boundaries
• Avoid duplicating content that belongs primarily in another viewpoint
• Each viewpoint owns its primary topics; other viewpoints reference, not repeat