Architecture Impact Analyzer

This skill analyzes code changes in HyperFleet component repositories and determines whether architecture documentation in the openshift-hyperfleet/architecture repository needs to be updated.

When to Use This Skill

This skill activates automatically when users:

Ask "analyze architecture impact"
Ask "check if docs need update"
Ask "should I update architecture docs?"
Request analysis of documentation impact from code changes
Want to know if their PR requires architecture documentation updates

Prerequisites

Zero setup required!

This skill automatically manages the architecture repository:

First run: Automatically clones architecture repository to cache
Subsequent runs: Automatically updates architecture repository (git pull)

The architecture repository is cached at:

~/.claude/plugins/cache/hyperfleet-devtools/architecture/

Features

Supported Components:

✅ hyperfleet-api (API Service component)
✅ hyperfleet-sentinel (Sentinel polling service)
✅ hyperfleet-adapter (Adapter event handler framework)
✅ hyperfleet-broker (Broker messaging library)

Analysis Scope:

✅ Uncommitted changes (default)
✅ Git commit range (e.g., main..HEAD)
✅ Last N commits (e.g., last 5)

Analysis Method:

Complete Document Reading: Reads entire documents (no truncation) for full context
Directory-Based Scope: Determines documents based on component directory structure
Universal Analysis Prompt: Works for all components (API, Sentinel, Adapter, Broker)
Single Comprehensive LLM Call: Provides all context at once for holistic analysis
No Keyword Filtering: Eliminates false positives from keyword-based guessing
Evidence-Based Decisions: LLM decisions grounded in complete code and documentation context

Parameters:

--range <git-range>: Analyze commits in a git range (e.g., --range main..HEAD)
--last <n>: Analyze last N commits (e.g., --last 5)

Execution Workflow

Phase 1: Environment Validation

Verify the execution environment and prerequisites:

Detect Current Repository and Component Type

# Get repository name from git remote and extract component name
REPO_URL=$(git remote get-url origin)
COMPONENT=$(echo "$REPO_URL" | grep -oE "hyperfleet-(api|sentinel|adapter|broker)")

# Set component type based on detected component
case $COMPONENT in
  hyperfleet-api)      COMPONENT_TYPE="API Service" ;;
  hyperfleet-sentinel) COMPONENT_TYPE="Sentinel" ;;
  hyperfleet-adapter)  COMPONENT_TYPE="Adapter" ;;
  hyperfleet-broker)   COMPONENT_TYPE="Broker" ;;
esac

Requirements:

Must be in a HyperFleet component repository (api, sentinel, adapter, or broker)

If not in a supported repository, show error:

❌ Error: Component not supported

Current repository: {detected_repo}

This skill supports the following HyperFleet components:
- hyperfleet-api (API Service)
- hyperfleet-sentinel (Sentinel)
- hyperfleet-adapter (Adapter)
- hyperfleet-broker (Broker)

Navigate to a supported repository and try again.

Parse Parameters and Determine Analysis Scope

# Parse optional parameters
RANGE=""
LAST=""

# Check for --range parameter
if [[ "$@" =~ --range[[:space:]]+([^[:space:]]+) ]]; then
  RANGE="${BASH_REMATCH[1]}"
  SCOPE="range:$RANGE"
fi

# Check for --last parameter
if [[ "$@" =~ --last[[:space:]]+([0-9]+) ]]; then
  LAST="${BASH_REMATCH[1]}"
  SCOPE="last:$LAST"
fi

# Default: uncommitted changes
if [ -z "$SCOPE" ]; then
  SCOPE="uncommitted"
fi

Verify Git Status

# Check if we're in a git repository
git rev-parse --git-dir

# Check if there are changes based on scope
if [ "$SCOPE" == "uncommitted" ]; then
  git status --porcelain
  # If no changes, show friendly message
elif [[ "$SCOPE" =~ ^range: ]]; then
  # Validate git range
  git rev-parse "$RANGE" 2>/dev/null || {
    echo "❌ Error: Invalid git range: $RANGE"
    exit 1
  }
elif [[ "$SCOPE" =~ ^last: ]]; then
  # Validate we have enough commits
  COMMIT_COUNT=$(git rev-list --count HEAD)
  if [ "$COMMIT_COUNT" -lt "$LAST" ]; then
    echo "⚠️  Warning: Only $COMMIT_COUNT commits available, requested last $LAST"
  fi
fi

Requirements:

Must be in a valid git repository
For uncommitted analysis: must have changes (modified, added, or deleted files)
For range analysis: git range must be valid

If no changes (uncommitted mode), show friendly message:

ℹ️  No code changes detected

There are no uncommitted changes to analyze.

Options:
- Make code changes and run this skill again
- Use --range to analyze a commit range (e.g., --range main..HEAD)
- Use --last to analyze recent commits (e.g., --last 5)

Ensure Architecture Repository Exists

Use the ensure_arch_repo.sh script to clone/update the architecture repository:
```
ARCH_REPO=$(bash {skill_base_directory}/ensure_arch_repo.sh)

if [ $? -ne 0 ] || [ -z "$ARCH_REPO" ]; then
  echo "❌ Error: Failed to ensure architecture repository"
  exit 1
fi

echo "✅ Architecture repository ready: $ARCH_REPO"
```
What this does:
- Checks if cached architecture repository exists at ~/.claude/plugins/cache/hyperfleet-devtools/architecture/
- If not exists: clones from GitHub
- If exists: updates with git pull origin main
- Returns the architecture repository path

Phase 2: Launch Analysis Agent

Once environment validation passes, launch the specialized architecture-impact-analyzer agent:

Use Task tool with:
- subagent_type: "hyperfleet-devtools:architecture-impact-analyzer:architecture-impact-analyzer"
- description: "Analyze architecture impact"
- prompt: "Analyze code changes in {repo_name} and determine architecture documentation impact.

          Repository: {repo_name}
          Component Type: {component_type}
          Analysis Scope: {scope}
          Git Range: {range} (if applicable)
          Last N Commits: {last} (if applicable)

          Please provide a detailed impact analysis report."

Context Passed to Agent:

Repository name (e.g., "hyperfleet-api", "hyperfleet-sentinel", "hyperfleet-adapter", "hyperfleet-broker")
Component type (e.g., "API Service", "Sentinel", "Adapter", "Broker")
Analysis scope (e.g., "uncommitted", "range:main..HEAD", "last:5")

Expected Agent Output: The agent will return a structured markdown report containing:

Summary (impact level, docs affected)
Changed files and their impact
Documentation update recommendations
Next steps

Phase 3: Present Results

Format and display the agent's analysis report to the user:

Display Report
- Show the complete report to the user
- Highlight key findings:
  - Impact level (HIGH/MEDIUM/LOW)
  - Number of documents requiring updates

Provide Next Steps

If documentation updates are needed:

📋 Next Steps:

1. Review the documentation update recommendations above
2. Update the identified sections in the architecture repository
3. Submit a PR to openshift-hyperfleet/architecture
4. Link the architecture PR to your code PR

Tip: You can use the hyperfleet-jira:jira-ticket-creator skill to create
tracking tickets for documentation updates.

If no updates needed:

✅ No architecture documentation updates required

Your changes don't impact existing architecture documentation.
You can proceed with your PR.

Error Handling

Error: Not in HyperFleet Repository

❌ Error: Not a HyperFleet repository

Current directory: {cwd}
Detected repository: {repo_name}

This skill only works in HyperFleet component repositories.

Supported repositories:
- hyperfleet-api (API Service)
- hyperfleet-sentinel (Sentinel)
- hyperfleet-adapter (Adapter)
- hyperfleet-broker (Broker)

Navigate to a HyperFleet repository and try again.

Error: Unsupported Component

❌ Error: Component not supported

Current repository: {repo_name}

This skill supports the following HyperFleet components:
- hyperfleet-api (API Service)
- hyperfleet-sentinel (Sentinel)
- hyperfleet-adapter (Adapter)
- hyperfleet-broker (Broker)

Please navigate to a supported HyperFleet repository and try again.

Error: No Changes Detected

ℹ️  No changes to analyze

There are no uncommitted changes in the repository.

To use this skill:
1. Make code changes to your repository
2. Run this skill again before committing

Or use alternative analysis modes:
- --range main..HEAD : Analyze commits in a branch
- --last 5 : Analyze last 5 commits

Examples:
  analyze impact --range main..HEAD
  analyze impact --last 5

Error: Invalid Git Range

❌ Error: Invalid git range

Range specified: {range}

The git range is not valid. Please check:
- Both refs exist (e.g., main, HEAD, branch names, commit hashes)
- The range syntax is correct (e.g., main..HEAD, abc123..def456)

Examples of valid ranges:
  --range main..HEAD
  --range feature-branch..HEAD
  --range abc1234..def5678

Error: Architecture Repository Failed

❌ Error: Failed to setup architecture repository

The architecture repository could not be cloned or updated.

Possible causes:
- Network connectivity issues
- GitHub authentication required
- Disk space issues

Please check your network connection and try again.

Error: Agent Execution Failed

❌ Error: Analysis agent failed

The architecture-impact-analyzer agent encountered an error:
{error_message}

Please try again or contact the HyperFleet DevTools team if the issue persists.

Debug information:
- Repository: {repo_name}
- Component: {component_type}
- Analysis scope: {scope}

Tips for Users

Before submitting a PR:

Run this skill to check documentation impact
Address any HIGH priority documentation updates
Create JIRA tickets for MEDIUM/LOW priority updates if needed
Link documentation PRs to your code PR

For best results:

Run analysis when your changes are complete but not yet committed
Review the full report, not just the summary
Prioritize HIGH impact documentation updates

Integration with other skills:

Use hyperfleet-jira:jira-ticket-creator to create tracking tickets for doc updates
Use hyperfleet-architecture to understand existing documentation structure

Architecture Impact

Architecture Impact Analyzer

When to Use This Skill

Prerequisites

Features

Execution Workflow

Phase 1: Environment Validation

Phase 2: Launch Analysis Agent

Phase 3: Present Results

Error Handling

Error: Not in HyperFleet Repository

Error: Unsupported Component

Error: No Changes Detected

Error: Invalid Git Range

Error: Architecture Repository Failed

Error: Agent Execution Failed

Tips for Users

More from openshift-hyperfleet/hyperfleet-claude-plugins

jira story point estimator

jira ticket creator

jira-story-pointer

review-pr

hyperfleet architecture

jira ticket triage