Houston

Houston is a set of Claude Code agents and skills for Satellite test failure analysis. It fetches test failures from Jenkins, resolves the relevant test source code from robottelo/airgun/nailgun, and pulls in product code from foreman/katello/foreman_rh_cloud for context. It pairs each failure with its stacktrace, test fixtures, imports, and related product code, then produces analysis reports with root cause grouping and suggested fixes.

Reports identify whether failures are test bugs or product bugs. All suggested fixes target the test repositories — no changes are proposed to product code. A knowledge base of verified fixes from past PRs is searched before each analysis to improve recommendations over time.

Prerequisites

• Python 3.12+
• Claude Code
• GitHub CLI (gh) authenticated — used to fetch PR diffs

Setup

1. Install the package in a virtual environment:

   python -m venv .venv
   source .venv/bin/activate
   pip install -e .

2. Create your config from the example:

   cp resources/config/settings.yaml.example resources/config/settings.yaml

3. Edit resources/config/settings.yaml — the only fields you need to fill in are your Jenkins and GitHub credentials. Everything else has working defaults.

   jenkins:
     url: https://your-jenkins.example.com
     user: your-username
     token: your-api-token   # Jenkins API token, not your password
   
   github:
     token: ghp_...          # Personal access token with repo scope

4. Test your connections:

   houston config --validate

   This confirms Houston can reach Jenkins and GitHub. If either fails, check your credentials.

You can also run houston config --init for an interactive setup wizard that walks you through each field.

Usage

@analyze-build agent (recommended)

Mention the agent in Claude Code to run the full pipeline end-to-end — it gathers failure data from Jenkins, searches the knowledge base for known fixes, analyzes each failure with test and product code context, and writes a report to resources/analysis/.

@analyze-build proton/ipv4/sat-stream-rhel9-Insights-Advisor --build 35
@analyze-build proton/ipv4/sat-stream-rhel9-RHCloud --build 1019 --limit 5

Individual skills

Each step of the pipeline is also available as a standalone skill. Useful when you want to re-run just one part — e.g., re-analyze after updating the knowledge base, or gather data now and analyze later.

Skill	Purpose
/analyze-build	Full pipeline — gather, search, analyze, and report
/gather-failures	Fetch Jenkins failures and generate context file
/search-fixes	Search knowledge base for known fixes
/analyze-failures	Analyze context file and write report
/record-fix	Import a verified fix from a merged PR
/compare-builds	Compare two builds (new vs recurring failures)

CLI

The CLI runs outside of Claude Code — it handles data gathering and knowledge base management without any AI. Useful for scripting, automation, or managing fixes and config independently.

houston analyze "<job-path>" --build <number> [--limit N] [--type TYPE] [--no-cache] [-v]
houston search <query> [--test-id ID] [--component NAME] [--limit N]
houston record-fix <PR-URL> --test-id "..." --error-pattern "..." --root-cause "..." --fix-description "..."
houston feedback <rec-id> --worked|--failed [--notes "..."]
houston sync [--repos-only] [--prs-only]
houston config --show|--init|--validate

Run houston <command> --help for full option details.

Knowledge Base

Houston maintains a knowledge base of verified fixes from past PRs in resources/fixes/. Each time an analysis runs, this knowledge base is searched first so known solutions can be surfaced immediately instead of re-diagnosing the same issues. The more fixes recorded, the better the recommendations get.

/record-fix https://github.com/SatelliteQE/robottelo/pull/1234

Tips

• Use the full job path: proton/ipv4/sat-stream-rhel9-Insights-Advisor
• --build is a flag, not positional: --build 35
• Start with --limit 1 when testing
• Run houston sync periodically to keep repo clones fresh