Human-in-the-Loop Checkpoints

X2A Convertor integrates human review at critical decision points to ensure quality, compliance, and correctness.

Why Human Checkpoints?

AI-powered automation accelerates migration but cannot replace human judgment for:

Architectural decisions: Migration priority, module grouping
Business logic validation: Edge cases, regulatory requirements
Risk assessment: Production impact, rollback strategies
Quality gates: Compliance with organizational standards

flowchart LR
    AI[AI Agent<br/>Fast, consistent] --> Output[Generated Artifact]
    Output --> Human{Human Review<br/>Strategic, contextual}
    Human -->|Approve| Next[Next Phase]
    Human -->|Refine| AI
    Human -->|Manual Fix| Manual[Manual Intervention]

    style AI fill:#e3f2fd
    style Human fill:#fff3e0
    style Next fill:#e8f5e9

Checkpoint 1: Init Plan Review

Trigger

After app.py init completes

Artifact

migration-plan.md

Review Checklist

Repository Structure

All expected cookbooks/modules identified
No critical modules missing
External dependencies correctly detected

Dependency Analysis

Dependency graph accurate
Circular dependencies flagged
External Supermarket cookbooks noted

Migration Strategy

Recommended order aligns with deployment architecture
Critical infrastructure components prioritized appropriately
Complexity estimates reasonable

Decision Points

Adjust migration order

# Re-run with specific guidance
uv run app.py init --source-dir ./chef-repo \
  "Prioritize security and compliance cookbooks first"

Exclude certain modules
- Document exclusions in plan
- Handle manually or defer
Approve and proceed
- Commit migration-plan.md to version control
- Move to analyze phase

Checkpoint 2: Module Specification Review

Trigger

After app.py analyze completes for each module

Artifact

migration-plan-<module>.md

Review Checklist

File Mappings

All recipes are described
Templates correctly identified for conversion
Static files (files/) mapped appropriately

Variable Mapping

Node attributes mapped to facts/variables
Secrets and sensitive data flagged

Decision Points

Request refinement

# Re-run with clarifications
uv run app.py analyze --source-dir ./chef-repo \
  "Focus on SSL configuration details in nginx-multisite"

Manual specification adjustments
- Edit migration-plan-<module>.md directly
- Document custom translation requirements
Approve and proceed
- Commit specification
- Trigger migrate phase

Checkpoint 3: Generated Code Review

Trigger

After app.py migrate completes

Artifact

ansible/roles/<module>/ directory

AAP Collection Discovery (Optional)

When AAP (Ansible Automation Platform) integration is configured, the migrate phase automatically queries your Private Automation Hub (Galaxy) to discover reusable collections.

Requirements:

AAP_CONTROLLER_URL: AAP Controller base URL
AAP_OAUTH_TOKEN: OAuth token for authentication
AAP_GALAXY_REPOSITORY: Repository to search (default: published)

What happens:

The discovery agent analyzes your migration plan
Searches the Private Hub for relevant collections (e.g., nginx, redis, security)
Verified collections are added to the role’s requirements.yml
The write agent uses discovered collections in generated tasks

Example output:

# ansible/roles/<module>/requirements.yml
collections:
- name: company.redis
  version: 1.0.0

# ansible/roles/<module>/tasks/main.yml
- name: Configure Redis
  ansible.builtin.include_role:
    name: redis
    collections:
      - company.redis
  vars:
    redis_port: 6379
    redis_requirepass: redis_secure_password_123

Benefits:

Reuse existing collections from your organization’s Private Hub
Reduce migration effort by leveraging pre-built roles
Ensure consistency with organizational standards

If no AAP_CONTROLLER_URL is configured, this step is skipped and migration proceeds without collection discovery.

Review Checklist

Structure

Role follows Ansible best practices
Files organized in standard directories
Naming conventions consistent

Task Logic

Task order matches recipe execution
Idempotency maintained
Error handling appropriate

Templates

Jinja2 syntax correct
Variables match defaults
Conditional blocks translated

Collections (if AAP enabled)

requirements.yml contains verified collections
Discovered collections match expected functionality
Collection versions are appropriate

Lint Status

No ansible-lint errors
Warnings addressed or documented
Code passes organization standards

Example Review

# ansible/nginx-multisite/tasks/main.yml
---
- name: Install nginx
  package:
    name: nginx
    state: present
  tags: ["nginx", "packages"]

- name: Configure nginx main config
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: "0644"
  notify: Reload nginx

- name: Ensure nginx is running
  service:
    name: nginx
    state: started
    enabled: true
  tags: ["nginx", "service"]

What to Look For:

Does execution order match Chef recipe?
Are handlers properly defined and notified?
Are tags useful for selective runs?

Testing Recommendations

Before production, test in isolated environment:

# Syntax check
ansible-playbook --syntax-check site.yml

# Dry run
ansible-playbook --check site.yml

# Run against test server
ansible-playbook -i test-inventory site.yml --tags nginx

# Verify idempotency
ansible-playbook -i test-inventory site.yml --tags nginx
# Second run should show no changes

Decision Points

Iterate on generation

# Adjust and regenerate
uv run app.py migrate ... "Fix handler naming to match organizational standards"

Manual fixes
- Edit generated files directly
- Document changes for future reference
Approve and proceed to publish
- Commit generated role
- Proceed to publish phase

Checkpoint 4: Published Deployment Review

Trigger

After app.py publish-project completes (and optionally publish-aap)

Artifact

Local Ansible project directory: <project-id>/ansible-project/
AAP Project + Project Update (if publish-aap was run)

Review Checklist

Deployment structure follows Ansible Project conventions (collections/, inventory/, roles/, playbooks/)
Local deployment structure created successfully
AAP Project was created/updated and a Project Update was triggered successfully (if using publish-aap)

Decision Points

Project structure issues
- Re-run publish-project to regenerate; on first module the full skeleton is recreated
Configuration adjustments
- Edit generated files in the project directory
- Re-run publish-project if major changes needed
Approve for production
- Push project to a git repository
- Run publish-aap to sync to AAP Controller
AAP integration issues
- AAP integration is env-driven via the separate publish-aap command
- Required when enabled:
  - AAP_CONTROLLER_URL
  - AAP_ORG_NAME
  - Auth: AAP_OAUTH_TOKEN or AAP_USERNAME + AAP_PASSWORD
- Optional:
  - AAP_PROJECT_NAME (otherwise uses --project-id or inferred from repository URL)
  - AAP_SCM_CREDENTIAL_ID (required for private SCM repos)
  - AAP_CA_BUNDLE (path to PEM/CRT CA cert for private PKI / self-signed)
  - AAP_VERIFY_SSL (true/false)
  - AAP_TIMEOUT_S
  - AAP_API_PREFIX (default: /api/controller/v2)
- If AAP sync fails, re-run publish-aap after fixing AAP configuration (or trigger a sync manually from the AAP UI)
For information on obtaining AAP Tokens and credentials, see the AAP documentation.

Audit Trail

All checkpoints should be documented on git.