analyse-design-gaps - SKILL.md Agent Skill

name: analyse-design-gaps description: Compare two design inventories produced by inventory-design and emit a structured gap artifact whose prose paragraphs satisfy the extract-work-items cue-phrase contract. Use after running inventory-design for both a current and target design surface. The resulting gap artifact under meta/design-gaps/ feeds directly into /accelerator:extract-work-items to produce actionable work items. argument-hint: "[current-source-id] [target-source-id]" disable-model-invocation: true allowed-tools: - Bash(${CLAUDE_PLUGIN_ROOT}/scripts/config-) - Bash(${CLAUDE_PLUGIN_ROOT}/skills/design/analyse-design-gaps/scripts/)

Analyse Design Gaps

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-context.sh !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-context.sh analyse-design-gaps !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-agents.sh

If no "Agent Names" section appears above, use these defaults: accelerator:reviewer, accelerator:codebase-locator, accelerator:codebase-analyser, accelerator:codebase-pattern-finder, accelerator:documents-locator, accelerator:documents-analyser, accelerator:web-search-researcher.

Design inventories directory: !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-path.sh research_design_inventories Design gaps directory: !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-path.sh research_design_gaps

You are tasked with comparing two design inventories and producing a structured design-gap artifact. The artifact's prose paragraphs must satisfy the extract-work-items cue-phrase contract so they flow into the work-item lifecycle without manual editing.

Steps

1. Resolve Each Source-Id to Its Inventory

For each of [current-source-id] and [target-source-id]:

a. Validate format: must match ^[a-z0-9][a-z0-9-]*$. Report a clear error naming offending characters if not.

b. Glob <design_inventories>/*-{source-id}/ (excluding leading-dot directories).

c. Zero matches: exit non-zero with:

error: source-id '<id>' did not match any inventory under <root>. Available source-ids: <comma-separated list>. Run /accelerator:inventory-design <id> <location> first.

d. Read frontmatter for each match. If an inventory.md is missing, unparseable, or lacks a status field, treat it as superseded and log a one-line warning naming the directory.

e. Filter to status != superseded (also exclude leading-dot directories). If multiple remain (crashed prior supersede step), apply the resolver tiebreaker:

Highest sequence number in frontmatter (primary — robust against clock skew)
Directory mtime, newest first (secondary — for equal-sequence concurrent writes)
YYYY-MM-DD-HHMMSS directory-name prefix, newest first (final)

Emit a one-line warning naming any non-selected directories when more than one remained after filtering.

f. Record the resolved absolute paths in the gap artifact frontmatter as current_inventory and target_inventory.

2. Read Both Inventories

Read each resolved inventory.md in full into context.

3. Compute Structural Diff

Compare the two inventories across five categories:

Token Drift — colour, typography, spacing tokens present in current but missing from target, or vice-versa; tokens with changed values
Component Drift — components present in both but with structural changes (variant count, prop changes, composition changes)
Screen Drift — screens/routes that have changed navigation structure, state matrix, or layout
Net-New Features — features present in target but not in current
Removed Features — features present in current but not in target

If a category has no differences, omit its H2 section from the artifact rather than writing an empty section.

4. Write Gap Prose

For each non-empty category, write at least one paragraph whose prose satisfies the cue-phrase contract used by extract-work-items. Each paragraph must contain one or more of:

"we need to …" / "we need a …"
"users need …"
"the system must …"
"Implement …" (capital letter on the named feature)

Guidance per category:

Token Drift: describe specific tokens to migrate, add, or remove. Example: "We need to migrate the 14-colour primary scale to the 8-token system defined in the target."
Component Drift: describe the structural changes needed. Example: "Users need a five-variant Button — the current implementation has two variants while the target design specifies five."
Screen Drift: describe changes to navigation structure or states. Example: "The system must support a redesigned Settings navigation pattern matching the target's two-level sidebar."
Net-New Features: introduce the feature and its scope. Example: "Implement Search to expose Cmd+K activation, query input, and recent-history preview panels."
Removed Features: flag for confirmation before removal. Example: "The legacy Analytics tab is present in the current implementation but absent from the target. We need to confirm with stakeholders whether it should be removed before proceeding."

Avoid bare structural headings without actionable content. Every non-empty H2 must contain at least one paragraph meeting the cue-phrase contract.

5. Run Cue-Phrase Audit

After generating the gap body, run:

${CLAUDE_PLUGIN_ROOT}/skills/design/analyse-design-gaps/scripts/audit-cue-phrases.sh \
  "<draft-body-path>"

On failure: the script names the offending H2 sections. Revise only those sections while keeping passing sections byte-identical. Re-run the audit. After three consecutive failures, write the rejected body to:

<design_gaps>/.YYYY-MM-DD-{current-source-id}-vs-{target-source-id}.draft.md

with a note at the top naming the failed sections, then report the failure and the draft path to the user. Do not write the artifact to its final path.

The frontmatter timestamp is generated once before the first write attempt and reused across retries.

6. Generate Metadata

Run:

${CLAUDE_PLUGIN_ROOT}/skills/design/analyse-design-gaps/scripts/gap-metadata.sh

7. Populate frontmatter and write artifact

Use the design-gap template:

!`${CLAUDE_PLUGIN_ROOT}/scripts/config-read-template.sh design-gap`

Before writing the artifact file, substitute every field below with the indicated value, using the helper output captured in Step 6 (Current Date/Time (UTC):):

type: ← design-gap
id: ← the filename stem (the file path computed below without .md), always quoted as a YAML string
title: ← Design Gap Analysis: {current-source} → {target-source}
date: ← the Current Date/Time (UTC): value
author: ← the author resolved per the standard chain (config → VCS user → prompt)
producer: ← analyse-design-gaps
status: ← draft
current_inventory: ← the resolved absolute path to the current inventory's inventory.md
target_inventory: ← the resolved absolute path to the target inventory's inventory.md
last_updated: ← the same Current Date/Time (UTC): value
last_updated_by: ← the same value resolved for author
schema_version: ← 1 (bare integer)

Optional linkage keys are omit-by-default (ADR-0040): the template shows each as ""/[], but write a key into the artifact only when it has a value, and omit it entirely otherwise (do not carry the empty placeholder through). The current_inventory: / target_inventory: keys above are always-valued and not subject to this rule.

parent: ← the work item this gap analysis supports, as a typed-linkage ref ("work-item:NNNN"). Fill when the analysis has an owning work item; otherwise omit the key.
relates_to: ← list of typed-linkage refs to related artifacts (["design-inventory:NNNN", ...]). Fill when relationships are explicit; otherwise omit the key.

The design-gap artifact is not code-state-anchored — the helper's Current Revision: and Repository Name: output is ignored here even when present.

Write to:

<design_gaps>/YYYY-MM-DD-{current-source-id}-vs-{target-source-id}.md

The References section must record:

The resolved inventory directory path for each source-id
Any resolver warnings emitted in Step 1

8. Present Summary

Report:

The artifact path
Count of non-empty drift categories
Any resolver warnings (multi-match or corrupt-frontmatter)
Whether the cue-phrase audit required revisions

Suggest next steps:

Run /accelerator:extract-work-items <gap-file> to generate work items

Important Guidelines

Empty drift categories are omitted — do not write placeholder sections.
The sequence tiebreaker is authoritative; do not rely on directory-name date alone.
Never fabricate observations. Write only what differs between the two inventories.
The cue-phrase audit is programmatic enforcement, not a style suggestion. Revise failing sections until the audit passes or the three-attempt limit is reached.

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-instructions.sh analyse-design-gaps