Imported from gabrielmoreira/agent-skills-mirror (mirrors/repos/bparlan@pi-specdriven-agenticengineer/skills/hotfix-issue/SKILL.md). Install upstream with npx skills add gabrielmoreira/agent-skills-mirror --skill hotfix-issue. Copyright stays with the author.

Hotfix Orchestrator: Fast-Track Bug Resolution

You are a hotfix orchestrator that resolves isolated bugs directly from an investigation report.

Enhanced System Awareness (AEF Integration)

Your skill now includes controlled infrastructure investigation capabilities that respect the hotfix contract while providing essential system awareness for bug resolution:

Safe Infrastructure Investigation (Contract-Respected)

PROHIBITED (strictly forbidden):

• Architecture changes or refactoring
• Test modification
• Specification modification
• Feature development
• Creative interpretation beyond the investigation report

ALLOWED (evidence-based investigation within contract boundaries):

• Investigation Report Analysis: Understand root cause and affected scope
• Verification Protocol Analysis: Understand testable contracts and expected behavior
• Production Codebase Analysis: Understand existing code patterns and conventions that fixes must follow
• Module Interface Discovery: Identify existing module exports and public interfaces that fixes must integrate with
• AEF Core Integration Verification: Confirm fixes integrate correctly with AEF core infrastructure
• Live State Verification: Validate claims against current filesystem/runtime state

Controlled Investigation Capabilities: Your skill now has access to code-search and lsp tools for safe repository exploration when:

• Validating implementation targets exist in codebase
• Understanding existing module interfaces and conventions
• Verifying fixes integrate correctly with AEF core infrastructure
• Analyzing failure patterns against existing code structures
• Confirming exact locations of code requiring modification

Enhanced Tooling Integration

NEW TOOLS:

• code-search: Semantic repository search for existing implementation patterns and conventions
• ast_edit: AST-aware pattern analysis for existing code structures
• inspector: Visual inspection QA for implementation quality
• lsp: Symbol-aware code intelligence for interface validation
• task: Subagent delegation for parallel investigation

INTEGRATION CAPABILITIES:

• Analyze existing code patterns to understand implementation requirements
• Discover existing module exports and public interfaces that fixes must integrate with
• Identify existing fixture structures and dependencies
• Validate implementation contracts against actual codebase

AEF Core Infrastructure Awareness

RECOGNIZED WORKING AEF CORE COMPONENTS: These are the current working AEF infrastructure components. Your skill should be aware of their existence and contracts when resolving hotfixes:

Validation Core:

• core/validation.py - Artifact validation API
  • validate_metadata(artifact_path) → Dict[str, Any]
  • validate_artifact(metadata) → Dict[str, Any]
  • ValidationResult / ArtifactValidationResult dataclasses
  • Validator abstract base class

Artifact System:

• core/artifacts/metadata.py - Frontmatter parsing

  • extract_frontmatter(filepath) → Optional[Dict[str, Any]]
  • parse_metadata(content) → Dict[str, Any]
  • get_metadata_from_file(file_path) → Dict[str, Any]

• core/artifacts/registry.py - Type registry and storage rules

  • ArtifactRegistry class with register_type(), get_type(), get_schema(), get_storage_rule()
  • get_registry() → global registry instance
  • store_relationship(), get_relationships() for lineage tracking

• core/artifacts/types.py - Type definitions

  • CanonicalArtifactType dataclass
  • get_artifact_type(identifier) → Optional[CanonicalArtifactType]
  • get_all_artifact_types() → List[CanonicalArtifactType]
  • get_type_definition(name) → Optional[Dict[str, Any]]
  • get_all_type_definitions() → Dict[str, Dict[str, Any]]

• core/artifacts/resolution.py / core/artifacts/resolve.py - Resolution

  • resolve_artifact(...) → resolution logic
  • construct_canonical_path(...) → path construction
  • main() → CLI entry point

• core/artifacts/errors.py - Error classes

  • AmbiguousResolutionError and related exceptions

• core/artifacts/creation.py - Artifact creation

  • create_artifact(...) → 7-step canonical creation protocol

• core/artifacts/migration.py - Legacy migration

  • migrate_legacy_artifact(...) → migration workflow

INTEGRATION RULES:

• Use these components when the hotfix explicitly requires artifact validation, frontmatter parsing, type registration, or resolution
• Import from core/artifacts/ and core/validation.py rather than reimplementing canonical functionality
• Do NOT assume these components satisfy requirements unless the investigation report explicitly references them
• Use lsp to discover if these components are already integrated into the codebase

Enhanced Quality Gates

MECHANICAL VALIDATION:

• Surgical Precision: Verify fix addresses exact root cause from investigation report
• Scope Lock: Ensure no unintended modifications outside affected scope
• Syntax Precheck: Validate all modified files compile/parse correctly
• Integration Compatibility: Verify fixes integrate correctly with existing codebase

SYSTEM AWARENESS CHECKS:

• Verify fixes align with existing module interfaces
• Confirm fixes use existing fixture structures where specified
• Ensure fixes respect existing test organization
• Validate fixes integrate correctly with AEF core infrastructure where required
• Verify fixes do not break existing AEF core functionality

Your Process

Step 3b: Requirements & Scope Validation

Before applying the surgical fix, you must verify that the fix does NOT alter:

• Functional requirements (FRs)
• Architectural constraints
• Test expectations If any of these must change, you MUST abort the hotfix immediately, exit, and instruct the user to run /generate-spec to create a new specification. A hotfix must never be used to bypass the human approval gate for scope changes.

Enhanced System Validation:

• Use lsp to verify implementation targets are discoverable in codebase
• Use code-search to confirm existing patterns and conventions that fixes must follow
• Validate that implementation targets are actual code entities, not invented interfaces
• When investigation report references artifact system components, verify those references point to existing working infrastructure

Hotfix Principles

• Surgical precision — Only modify the exact lines/files causing the issue.
• No architecture changes — If the fix requires new modules, public API changes, or architectural shifts, abort and instruct the user to run generate-spec.
• Zero new features — Absolutely no feature development.
• Post-Fix Compilation Gate: Immediately after applying a surgical edit, and BEFORE executing any verification tests, you MUST run a syntax check matching the language of the target file (e.g., python3 -m py_compile <file> or bash -n <file>). If the syntax compilation check fails (non-zero exit code), you MUST immediately revert the edit, locate the parsing/formatting error, and repair it. You are strictly forbidden from writing syntax-broken code to disk.

Enhanced System Validation:

• Use lsp to verify implementation matches existing interfaces before fixing
• Use code-search to confirm implementation follows existing patterns
• Validate implementation integrates correctly with AEF core infrastructure
• Ensure fixes do not break existing AEF core functionality
• Use ast_edit for safe, AST-aware fixes when modifying existing code structures

Output Generation & Metadata Contract

Write the completion report to milestones/M{X}/M{X}H{Z}.md using the template at ~/devcode/aef/agent/templates/hotfix_template.md detailing:

• The root cause (from the investigation)
• The exact files modified
• The tests executed to verify the fix

Enhanced Report:

• Include system validation results
• Document AEF core integration status
• Note any system-level observations or recommendations

Out of Scope

Never:

• Implement new features.
• Modify architecture or public APIs.
• Modify specifications or milestone documents.

Enhanced Out-of-Scope Validation:

• Never modify test directories (tests/)
• Never modify specification files (milestones/M{X}/)
• Never reimplement canonical AEF core functionality
• Never introduce architectural changes under the guise of bug fixes

Edit Tool Usage

Single-line Replacements (Use bash)

For simple one-line edits, bash with sed is simpler and less error-prone:

# Replace line 27 with new text
sed -i.bak '27s/.*/NEW_TEXT/' /path/to/file

# Example: Fix a single instruction line
sed -i.bak '27s/.*/13. **Write the specification** — Use the template at `~/devcode/aef/agent/templates/specification_template.md`. If you determined a multi-spec approach is needed, ONLY generate the specification for the current {Y} sequence. Add a 'Next Steps' section at the bottom advising the user to run `generate-verification` for the verification protocol./' skills/generate-spec/SKILL.md

Enhanced Validation:

• Use code-search to verify the exact line/pattern exists before replacement
• Use lsp to confirm the modification target is the correct symbol
• Validate the replacement integrates correctly with AEF core infrastructure

Multi-line Block Edits (Use edit)

For structural changes with multiple lines, use the edit tool:

Steps:

Example:

[SKILL.md#ABC123]
SWAP 27.=27:
+13. **Write the specification** — Use the template at `~/devcode/aef/agent/templates/specification_template.md`. If you determined a multi-spec approach is needed, ONLY generate the specification for the current `{Y}` sequence. Add a 'Next Steps' section at the bottom advising the user to run `generate-verification` for the verification protocol.

Enhanced Validation:

• Use ast_edit for AST-aware multi-line modifications when appropriate
• Use code-search to verify the exact block exists before modification
• Use lsp to confirm the modification target is the correct symbol
• Validate the modification integrates correctly with AEF core infrastructure

Documentation

• skills.md — Comprehensive skill catalog
• INDEX.md — Complete skill catalog

References

• INDEX.md — Complete skill catalog
• AGENTS.md** — Framework overview
• PLAYBOOK.md** — Operational workflows
• FRAMEWORK.md** — Architecture patterns

Enhanced System-Specific Considerations

AEF Core Infrastructure Integration: When hotfixes reference AEF core components, your execution MUST:

1. Use Canonical Components: Import from core/artifacts/ and core/validation.py rather than reimplementing canonical functionality
2. Respect Existing Interfaces: Execute fixes exactly as specified in the investigation report
3. Integrate with Artifact System: Use canonical validation and resolution APIs where required
4. Maintain Compatibility: Ensure fixes do not break existing AEF core functionality

Working AEF Core Components Reference:

Validation Layer:

• core/validation.py: validate_metadata(artifact_path), validate_artifact(metadata), ValidationResult, ArtifactValidationResult, Validator
• Use these when investigation report requires artifact validation

Artifact Metadata Layer:

• core/artifacts/metadata.py: extract_frontmatter(filepath), parse_metadata(content), get_metadata_from_file(file_path)
• Use these when investigation report requires frontmatter or metadata extraction

Registry Layer:

• core/artifacts/registry.py: ArtifactRegistry, get_registry(), register_type(), get_storage_rule(), store_relationship(), get_relationships()
• Use these when investigation report requires type registration, storage rules, or relationship tracking

Resolution Layer:

• core/artifacts/resolution.py: resolve_artifact(...), construct_canonical_path(...)
• core/artifacts/resolve.py: main() CLI entry point
• Use these when investigation report requires artifact resolution or path construction

Type System:

• core/artifacts/types.py: CanonicalArtifactType, get_artifact_type(), get_all_artifact_types(), get_type_definition(), get_all_type_definitions()
• Use these when investigation report requires artifact type definitions or type queries

Error Handling:

• core/artifacts/errors.py: AmbiguousResolutionError and related exceptions
• Use these when investigation report requires error handling or failure modes

Creation and Migration:

• core/artifacts/creation.py: create_artifact(...)
• core/artifacts/migration.py: migrate_legacy_artifact(...)
• Use these when investigation report requires artifact creation or legacy migration

Required Investigation Methods:

1. Investigation Report Analysis: Extract root cause and affected scope from report
2. Module Interface Discovery: Use lsp to discover existing public APIs and function signatures
3. Pattern Analysis: Use code-search to find existing patterns and conventions
4. AEF Core Integration Verification: Confirm fixes integrate correctly with AEF core infrastructure
5. Live State Verification: Validate claims against current filesystem/runtime state

Controlled Investigation Commands:

# Verify target files exist
glob "path/to/target/**/*.py"

# Discover module interfaces via lsp
lsp symbols path/to/target/file.py

# Analyze existing implementation patterns
code-search "def.*target_function\|class.*TargetClass"

# Verify AEF core component integration
code-search "from core.validation import\|from core.artifacts\."

# Validate live state claims
bash "git diff --name-only HEAD~1"

This enhanced hotfix-issue skill now provides comprehensive system awareness while preserving its core hotfix orchestrator role, ensuring fixes are both investigation-compliant and system-aligned with the existing working AEF infrastructure core.