handback-to-aifactory

name	handback-to-aifactory
description	From an AIFactory project, receive a correction hand-back from PFactory (sister project). When PFactory's tests found problems, this previews the prepared correction and applies it to the original spec via AIFactory's QA Fixer (writes QA_FIX_REQUEST.md + runs the fixer). The reverse of /handover-to-pfactory.
when_to_use	When PFactory finished testing an AIFactory feature, found failures, and you want AIFactory to fix the code. Triggers — "apply the pfactory correction", "/handback-to-aifactory", "have aifactory fix what pfactory found".
allowed-tools	["mcp__aifactory__task_apply_correction","mcp__aifactory__task_status","mcp__pfactory__task_status","Bash","Read"]

/handback-to-aifactory (AIFactory companion)

This skill lives inside an AIFactory project and is the user-facing trigger for applying a PFactory correction to a spec. It is the mirror image of PFactory/.claude/skills/handback-to-aifactory/. Both share the same procedure; the only difference is which repo the slash command is typed from.

It pairs with /handover-to-pfactory to close the loop:

/handover-to-pfactory → PFactory tests → (failures) → /handback-to-aifactory
   → AIFactory QA Fixer fixes the spec → re-run PFactory to verify

Installation

From the AIFactory repo root:

mkdir -p .claude/skills/handback-to-aifactory
cp /path/to/PFactory/companion-skills/aifactory-handback-from-pfactory/SKILL.md \
   .claude/skills/handback-to-aifactory/SKILL.md

The receiver this skill drives ships in AIFactory itself (issue olafkfreund/AIFactory#317): the REST route POST /api/tasks/{task_id}/apply-correction and the MCP tool task_apply_correction. Make sure AIFactory's web-server is running (port 3101) and — for the MCP path — that AIFactory's own MCP server is registered in your Claude Code MCP config so mcp__aifactory__task_apply_correction resolves.

When to use

• explicit /handback-to-aifactory
• "apply the pfactory correction"
• "have aifactory fix what pfactory found"

Procedure

1. Get the correction payload

The correction request lives in the PFactory workspace for the task: ~/.pfactory/workspaces/<project_id>/specs/<spec_id>/findings/handback_request.md (+ .json). If you have it, read it; if PFactory is on another host, have the operator paste the handback_request.md contents.

2. Identify the target spec

From handback_request.json, read aifactory_task_id — it's <project_id>:<spec_id> for the AIFactory spec to fix.

3. Preview, then apply

mcp__aifactory__task_apply_correction(
  project_id=..., spec_id=...,
  fix_request_md=<contents of handback_request.md>,
  source=<"triage" | "visual_inspection">,
  confirm=false        # preview — writes/starts nothing
)

Show the operator the preview (would_write). On a clear yes, call again with confirm=true — AIFactory writes QA_FIX_REQUEST.md onto the spec and runs the QA Fixer.

4. Report + (optionally) re-test

Report the spec + returned status (e.g. qa_fixing). When the fixer finishes, re-run PFactory to verify the fix: mcp__pfactory__task_rerun(task_id=...).

Failure modes

• Spec not found (404) → the aifactory_task_id doesn't match a current spec; check it was handed over from this project.
• MCP tool missing → register AIFactory's MCP server, or run the apply from the PFactory side: cd apps/backend && python -m agents.handback <spec_dir> --send.
• Fixer needs creds → the QA Fixer runs a real provider; ensure AIFactory's LLM provider is configured.