🇺🇸English

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:

1. 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.
    

2. 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

3. 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)
    

4. 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:

1. Display Report

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

2. 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:

1. Run this skill to check documentation impact
2. Address any HIGH priority documentation updates
3. Create JIRA tickets for MEDIUM/LOW priority updates if needed
4. 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

Weekly Installs

–

Repository

openshift-hyper…-plugins

GitHub Stars

5

First Seen

–

Security Audits

Gen Agent Trust HubPassSocketPassSnykWarn