twincat-build-fixer

name

twincat-build-fixer

description

Build TwinCAT 3 projects through Visual Studio 2022, parse TwinCAT and PLC compiler output, generate structured error reports, and drive iterative source fixes until the build is clean or a human decision is required. Use when Codex needs to modify TwinCAT source files, run VS2022-based builds, inspect build errors or warnings, and repeat the edit-build-check loop on .sln, .tsproj, .plcproj, .TcPOU, .TcGVL, and .TcDUT projects.

TwinCAT Build Fixer

Overview

Use this skill when the task is no longer just "understand the code" but "change the code and get it to build." This skill combines TwinCAT-aware reasoning with VS2022 build automation and structured build-report handling.

Read references/vs2022-build-loop.md for the end-to-end workflow and script usage. Read references/autofix-stop-rules.md when deciding whether to keep auto-fixing or stop and ask for human input.

Workflow

1. Confirm the build target

Before changing code, identify:

• solution path
• TwinCAT solution configuration such as Debug|TwinCAT RT (x64)
• whether the user wants background build or visible VS2022
• whether warnings should be fixed or only errors

Prefer background build for iterative loops.

2. Run the build through VS2022 automation scripts

Use the bundled scripts in scripts/:

• Invoke-TwinCATVs2022Build.ps1 to run a single VS2022 build
• Parse-TwinCATBuildLog.ps1 to classify errors, warnings, and messages
• Invoke-TwinCATBuildCycle.ps1 to run build plus parsing together
• Invoke-TwinCATAutoFixLoop.ps1 to repeat the cycle over multiple iterations
• Sync-TwinCATVs2022Solution.ps1 to reopen a matching already-open VS2022 solution after external file edits
• Open-TwinCATVs2022.ps1 to open the solution visibly when needed
• Invoke-CodexTwinCATFix.ps1 to convert a build report into a structured fix task

Prefer Invoke-TwinCATBuildCycle.ps1 or Invoke-TwinCATAutoFixLoop.ps1 for normal work. If the user already has the same solution open in VS2022, prefer the stable reload path by reopening that solution after edits instead of relying on a lightweight refresh.

3. Read the report before editing

Treat the parsed report as the source of truth for the next edit. Use it to identify:

• error count vs warning count
• exact message text
• referenced file paths
• whether the build already succeeded
• whether the issue is in user code, generated code, system libraries, or visualization dependencies

If the report points only to system libraries or third-party assets, be careful not to "fix" code that the project does not own.

4. Make the smallest safe TwinCAT edit

When fixing code:

• prioritize true compile errors over warnings
• edit only project-owned files unless the user explicitly approves broader changes
• preserve TwinCAT execution semantics, mappings, and data flow
• avoid speculative refactors during an error-fix pass
• if one fix may ripple across GVL/DUT/POU boundaries, explain that in the next report

5. Rebuild and decide whether to continue

Repeat the loop until:

• build errors reach zero
• only acceptable warnings remain
• the same error repeats without progress
• the issue requires ambiguous architectural or safety decisions
• the error originates in generated/system content that should not be changed automatically

Script Usage

Example commands:

.\scripts\Invoke-TwinCATBuildCycle.ps1 -SolutionPath 'D:\path\project.sln'
.\scripts\Invoke-TwinCATAutoFixLoop.ps1 -SolutionPath 'D:\path\project.sln' -MaxIterations 5
.\scripts\Open-TwinCATVs2022.ps1 -SolutionPath 'D:\path\project.sln'

Decision Rules

• Stop immediately if the requested fix touches safety logic, target routing, deployment, or online change behavior without clear user intent.
• Stop if the build error implies missing project context rather than incorrect code.
• Stop if the compiler output points to generated/system library content instead of editable project files.
• Continue automatically when the issue is a straightforward syntax, type, declaration, reference, or obsolete-API usage problem in project-owned files.

Typical requests this skill should handle

• "Build this TwinCAT project and fix the compile errors."
• "Keep iterating until the PLC build is clean."
• "Parse the TwinCAT build log and tell me what source file to edit."
• "Open the project in VS2022, but keep the normal fix loop headless."
• "Generate a structured fix task from the latest iteration report."