DOC: Capture recent CI lessons in Documentation/AI/ skill files

[hjmjohnson]

Update Documentation/AI/ skill files with CI lessons learned and revised attribution rules based on community feedback. Closes #6055.

Commit 1: CI lessons and code-review patterns

• git-commits.md, style.md — drop WIP: prefix, add BUILD:, document [WIP] PR-title workflow
• compiler-cautions.md — KWStyle enum class pitfall (§12), NumericTraits float range (§13)
• testing.md — GTest exception macros (ITK_TRY_EXPECT_EXCEPTION incompatible with GoogleTest)
• attribution.md — initial attribution rules
• code-review-lessons.md — new file capturing recurring review patterns

Commit 2: Revise attribution rules per #6055 feedback

Incorporates feedback from N-Dekker (#6055 comment), blowekamp (Discourse #7728 post #16), and dzenanz (#6055 comment):

• Remove AI trailers from commits — Tool-Assisted: and Assisted-by: trailers removed. AI disclosure moves entirely to PR description inside <details> blocks.
• Co-Authored-By: for AI → "discouraged" (was "never") — acknowledges N-Dekker's GitHub-linking-semantics argument while noting blowekamp's preference for no AI info in commits.
• Reviewer vs co-author distinction — Co-Authored-By: only for design-shaping feedback, not routine review. Per N-Dekker: "A reviewer may not completely agree with the PR... A co-author usually does."
• Stronger brevity guidance — PR descriptions must lead with 1-3 line visible summary; all longer analysis in collapsed <details> blocks. Per dzenanz: "commit messages and PR body should be concise."
• PR description is sole AI disclosure mechanism — commits are clean.

[greptile-apps]

Greptile Summary

Pure documentation update to five Documentation/AI/*.md skill files, capturing lessons from recent CI failures across PRs #6027–#6035. Changes cover: dropping WIP: commit prefix in favour of BUILD: and [WIP] PR-title workflow; KWStyle's enum class doxygen requirement; NumericTraits<float>::min() float-range semantics; SWIG %pythoncode %{…%} verbatim syntax; a new-class CI checklist; and GTest-compatible exception macros.

• The clang-tidy sub-sections (### 12a, ### 12b, ### 12c) inside the newly-renumbered §14 were not updated to ### 14a/14b/14c, leaving a numbering mismatch that could confuse an agent cross-referencing by number.

Confidence Score: 4/5

Safe to merge after fixing the stale sub-section numbers in §14 of compiler-cautions.md.

One P1 documentation inconsistency: sub-sections 12a/12b/12c inside the renumbered §14 (clang-tidy) were not updated. Since this file is used as a reference guide by AI agents, the numbering mismatch is a real (if minor) correctness issue for its intended consumers. All other changes are accurate and well-structured.

Documentation/AI/compiler-cautions.md — sub-section labels in §14 still carry old §12 numbers.

Important Files Changed

Filename	Overview
Documentation/AI/compiler-cautions.md	Adds §12 (KWStyle/Doxygen) and §13 (NumericTraits float range), renumbers old §12→14 and §13→15; sub-section labels 12a/12b/12c inside the newly-renamed §14 were not updated and remain stale.
Documentation/AI/conventions.md	Adds SWIG %pythoncode verbatim-form guidance and a 9-point new-class checklist; accurate and well-structured.
Documentation/AI/git-commits.md	Removes WIP: prefix, adds BUILD:, documents [WIP] PR-title workflow, and adds commit-length guidance; all correct.
Documentation/AI/style.md	Updates prefix list to replace WIP: with BUILD: and adds a cross-reference note; clean change.
Documentation/AI/testing.md	Adds a GTest-compatible exception-test section with correct EXPECT_THROW/ASSERT_THROW guidance; accurate.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[New ITK class or commit] --> B{Commit prefix check}
    B -->|WIP: used| C[ghostflow-check-main REJECTS]
    B -->|ENH or BUG or BUILD etc.| D[ghostflow OK]
    D --> E{enum class with doxygen comment?}
    E -->|no backslash-class tag| F[KWStyle CI FAILS]
    E -->|plain comment or backslash-class tag| G[KWStyle OK]
    G --> H{GTest exception test?}
    H -->|ITK_TRY_EXPECT_EXCEPTION| I[Compile error in TestBody]
    H -->|EXPECT_THROW or ASSERT_THROW| J[GTest OK]
    J --> K{Python wrapping?}
    K -->|Missing itkXxx.wrap| L[Python CI KeyError]
    K -->|wrap file present| M[CI GREEN]
    K -->|pythoncode single-brace with hash comment| N[SWIG preprocessor error]
    K -->|pythoncode verbatim form| M

Loading

Comments Outside Diff (1)

1. Documentation/AI/compiler-cautions.md, line 570-592 (link)

   Stale sub-section numbers after renumbering

   Section 12 (clang-tidy) was promoted to section 14, but its three sub-sections (### 12a, ### 12b, ### 12c) were not updated to ### 14a, ### 14b, ### 14c. An agent loading this file and following the numbering will see a mismatch: the parent heading says 14 while the children still say 12.

_{Reviews (1): Last reviewed commit: "DOC: Capture recent CI lessons in Docume..." | Re-trigger Greptile}

[blowekamp]

I have been using CMakeUSerPresets.json to hold predefined configuration of ITK such as "development", "wrapping", "system-libraries", or "doxygen". Currently I have some local instructions in .github-instructions.md

Specifically I have:

## Build and Testing

DO NOT USE pixie for development.

Use the CMakePresets.json and CMakeUserPresets.json files to configure the build environment: `cmake --preset PRESET_NAME` to configure the build and `cmake --build --preset PRESET_NAME` to build.

The full compilation of ITK and it's test suit is time consuming. Building specific targets can speed the development process.

To build targets `cmake --build --preset PRESET_NAME --target TARGET` should be used.

Each module name is also a build target for the module which include tests targets.

The test drivers are named such as ITKCommon1TestDriver, ITKCommonGTestDriver, or ITKIOImageBaseTestDriver.

Tests should be run with the `ctest --preset PRESET_NAME` command.

I have found these CMakePreset.json files very useful to manage different configurations, perhaps they could be more widely adopted? Not sure how user customization of these instructions should occur.

[hjmjohnson]

@blowekamp Are you suggesting changes to the proposed updates?

[blowekamp]

@hjmjohnson No. Just a question/conversation relate to these changes.

• What is the recommended way for local instructions on building or other local customization?
• Would adopting CMakePresets[User].json into the build/testing instruction be widely useful?

[hjmjohnson]

@hjmjohnson No. Just a question/conversation related to these changes.

• What is the recommended way for local instructions on building or other local customization?
• Would adopting CMakePresets[User].json into the build/testing instruction be widely useful?

@blowekamp Ahh... I see. My opinion "CMakePresets[User].json into the build/testing instruction be widely" would be widely useful. I've had some success with it, and I think it would be a way to codify, in an AI-friendly JSON format, more meaning than can be achieved with mixes of shell command-line options. I've made a note to make a WIP to promote discussion after some of my other open PR's have cleared.

[hjmjohnson]

@blowekamp @N-Dekker @thewtex @dzenanz I think these are in a reasonable state to consider now. After these updates, Greptile will be able to better enforce the "historical community perspectives" as represented by these rules extracted from various commit, PR-comment, and discourse comments.

[thewtex]

@N-Dekker does this look good to you?