doc-sync

name

doc-sync

description

Review and update project documentation for accuracy against the current codebase. Use when adding a class, renaming a type, changing workflow phases, updating dependencies, or modifying the package structure. Covers README.md, ARCHITECTURE.md, copilot-instructions.md, and SKILL.md files. Triggers: review docs, update documentation, update README, review ARCHITECTURE, sync docs, documentation review, doc sync, stale docs, inaccurate docs, docs out of date.

Documentation Sync

Review all project documentation for accuracy against the current source code, then apply corrections in place. Do not rewrite sections that are still accurate — only fix what is wrong or missing.

Documents in Scope

File	Primary risk of drift
README.md	Dependency versions, feature list
ARCHITECTURE.md	Class names, responsibilities, data flow
copilot-instructions.md	Versions, package structure, workflow phases, image formats
.github/skills/*/SKILL.md	File paths, class names, Gradle commands

---

Step 1 — Establish Ground Truth

Collect the authoritative facts from source before touching any document.

1a — Dependency versions

Read build.gradle.kts and note the current values for:

• Java version (toolchain languageVersion)
• JavaFX version (javafx { version = "..." })
• All library dependencies in the dependencies block (group, artifact, version)
• All Gradle plugin versions in the plugins block

1b — Source class inventory

List every .java file under src/main/java/ to get the complete set of current class names and their packages:

find src/main/java -name "*.java" | sort

1c — Supported image formats

Read ImageScannerService.java and extract the exact set of recognized file extensions. The scanner is the single source of truth for what formats are supported.

1d — Workflow phases

Count the phase controllers: FolderSelectionController + one controller per phase + any results/summary step. Read AppCoordinator.java to confirm the actual phase transition sequence.

1e — Package structure

Read the directory listing of src/main/java/net/markwalder/picturetriage/ to get the current sub-package list.

---

Step 2 — Review and Update ARCHITECTURE.md

This file is highest-risk because it names every class and describes its responsibility.

2a — Verify named classes exist

For each class name mentioned in ARCHITECTURE.md, confirm it exists in the source inventory from Step 1b. If a class has been renamed or removed, update or delete its entry.

2b — Verify new classes are documented

For each class in the source inventory, check whether it appears in ARCHITECTURE.md. Any class that is not a test class and not an inner class should have an entry. Add brief entries for missing classes in the appropriate layer section.

2c — Verify layer diagram

Check the ASCII diagram at the top. Confirm it still accurately reflects the layering — especially if a new layer or component has been introduced.

2d — Verify data flow

Read the data flow section at the bottom. Check that the service names and return types match the current service implementations. Update if signatures or flow has changed.

---

Step 3 — Review and Update README.md

3a — Feature list

Check each bullet in the Features section against the implemented phases and capabilities. Add bullets for new features; remove bullets for removed ones.

3b — Java version

Compare the stated Java requirement against the toolchain version from Step 1a.

3c — Dependency versions

Compare every dependency version listed in the README against the values from Step 1a. Update any version string that has changed.

3d — Build and run commands

Verify the documented Gradle commands (./gradlew build, ./gradlew run, etc.) are still valid. If new build tasks have been added (e.g., jpackage), confirm they are documented accurately.

---

Step 4 — Review and Update copilot-instructions.md

4a — Tech stack versions

Compare every version number in the "Tech Stack & Build Configuration" section against the values from Step 1a. Fix any that are out of date.

4b — Package structure block

Compare the package tree in the "Package Structure" section against the directory listing from Step 1e. Add missing sub-packages; remove deleted ones.

4c — Workflow phases list

Compare the numbered phase list in the "Workflow" section against the actual phase sequence from Step 1d. Update phase count, names, and descriptions to match.

4d — Supported image formats list

Compare the formats listed in the "Supported Image Formats" section against the extensions from Step 1c. The two must be identical (case-insensitive).

4e — Layer names and responsibilities

The "Architecture" bullet list is a summary of the layer descriptions in ARCHITECTURE.md. If any layer was renamed or its purpose changed, update this summary accordingly.

---

Step 5 — Review SKILL.md Files

For each file in .github/skills/*/SKILL.md:

5a — Verify file paths

Any file path mentioned (e.g., src/main/resources/.../application.css, build.gradle.kts) must still exist. Use file_search to confirm. Update paths that have moved.

5b — Verify class and method names

Any Java class, method, or field name mentioned must still exist in the source. Use grep_search to verify. Update names that have been renamed.

5c — Verify Gradle commands

Any Gradle task mentioned (e.g., dependencyUpdates, compileJava, dependencies --write-locks) must still be valid. Compare against build.gradle.kts task definitions.

---

Step 6 — Final Check

After all edits, re-read each changed document and confirm:

• No version number, class name, or file path was left in a stale state
• No section was accidentally restructured or its meaning changed
• Formatting is consistent with the rest of the document (heading levels, code fences, bold conventions)

Do not rewrite accurate prose for style. Only correct factual inaccuracies.