Repomatic Audit

Context

!ls .github/workflows/*.yaml 2>/dev/null !grep -h 'uses:.*kdeldycke/repomatic' .github/workflows/*.yaml 2>/dev/null | head -5 !grep -A5 '\[tool.repomatic\]' pyproject.toml 2>/dev/null || echo "No [tool.repomatic] section" !grep -E '^(subagents|skills|gitignore)\.location' pyproject.toml 2>/dev/null ![ -f repomatic/__init__.py ] && echo "CANONICAL_REPO" || echo "DOWNSTREAM"

Instructions

You perform a comprehensive audit of a downstream repository against the upstream kdeldycke/repomatic reference. This goes beyond what repomatic init workflows handles: it catches stale action versions in custom job content, missing workarounds, outdated configs, and conventions that can be borrowed from upstream.

This skill is for downstream repos only. If the context shows CANONICAL_REPO, tell the user this skill is not applicable.

Distinguishing real drift from intended absence

Before flagging an issue, verify that the gap isn't deliberate or covered by a runtime mechanism. Common false positives:

• [tool.repomatic] exclude is authoritative. Files listed there (like workflows/changelog.yaml or labels) are intentionally absent on disk. Do not report them as MISSING.
• Bundled defaults applied at runtime. Some config is materialized from the bundled template at runtime when the file is absent, so no on-disk copy is needed. Absence of these files is not a problem: it is the intended state when the user is happy with the bundled policy. Only flag DRIFT if the user wants to deviate from it. Exactly five tools carry such a fallback, the ones whose ToolSpec sets default_config in repomatic/tooling/tool_registry.py: actionlint, mdformat, ruff, yamllint and zizmor.
• A [tool.X] section is never a candidate for deletion. The inverse of the rule above, and the more expensive mistake. Every other tool has no default_config, so its resolution chain has no level 3 to fall back on: lychee, typos, mypy, pytest, coverage, bumpversion and uv are deployed into pyproject.toml by repomatic init, and that section is the only config the tool will ever see. Deleting it does not restore inheritance from a bundled default, it drops the tool to level 4 and runs it bare, silently discarding every rule the section held. Read the tool's default_config before proposing a section be dropped "to inherit upstream updates". Re-running repomatic init fixes a stale section only for the components marked SyncMode.ONGOING in repomatic/registry.py (lychee, typos, bumpversion, uv). It never revisits a mypy, pytest or coverage section after the first write: lint-repo warns on each bundled template entry such a section lacks, to copy by hand or decline on purpose.
• Generator artifacts vs user error. When local thin-callers diverge from upstream (e.g., extra workflow_dispatch:, missing paths:), the cause may be the upstream generator, not downstream tampering. Inspect repomatic/github/workflow_sync.py (generate_thin_caller, _adapt_trigger_paths, generate_workflow_header) before recommending the user re-run repomatic init to "fix" something init itself produced.
• Project-level claude.md may live under a sub-directory. [tool.repomatic] subagents.location and skills.location indicate a project where .claude/ is not at the root (e.g., dotfiles repos with dotfiles/.claude/CLAUDE.md). Search the configured location, not just ./CLAUDE.md.

When in doubt, search the upstream codebase to confirm whether a behavior is intentional. Read [tool.repomatic] in the local pyproject.toml carefully before declaring anything missing.

Scope selection

• all (default when $ARGUMENTS is empty): Run all audits below.
• workflows: Audit workflow files only.
• configs: Audit non-workflow config files only.
• upstream: Identify downstream innovations that could be contributed back to repomatic.

Fetching reference files

Fetch every reference file at the version the downstream repo has actually adopted, never at the tip of main. The Context block above prints the uses: pins; take the tag from there and pass it as ref on every call:

$ gh api "repos/kdeldycke/repomatic/contents/{path}?ref=vX.Y.Z" --jq '.content' | base64 -d

An unpinned fetch resolves to main, which carries unreleased work. Audited against it, every change waiting for the next release reads as downstream drift, and the "fix" that follows can be worse than the phantom problem: a [tool.X] section matching its adopted bundled template exactly gets reported as stale, because main has since grown entries no release has shipped yet.

Keep the two axes apart in the report, because only one of them is actionable:

• Drift is a difference against the adopted tag. Report it.
• Available in a newer release is a difference between the adopted tag and a later published one. That is an upgrade note, never a DRIFT row. Confirm the version actually exists with gh api repos/kdeldycke/repomatic/releases --jq '.[].tag_name'.
• Only on main is unreleased and belongs in neither list. The changelog's top section is headed with a .devN version and a "not released yet" warning; anything described there is not yet available to any downstream repo.

1. Workflow audit (workflows)

Thin-caller workflows

Compare each local thin-caller workflow against its reference. These should be identical (except for files listed in exclude). Flag:

• Extra triggers (e.g., spurious workflow_dispatch).
• Missing triggers.
• Version pin drift (different @vX.Y.Z tag).

Header-only workflows (e.g., tests.yaml)

The header (name, on:, concurrency:) is synced automatically, but custom job content is not. Compare the job content against the reference for:

• Stale action versions: e.g., actions/checkout, astral-sh/setup-uv — compare pinned versions. setup-uv carries a second, independent pin: a with: version: "X.Y.Z" input naming the uv it downloads. Absent, the runner installs whatever uv is newest, leaving the tool that enforces every cooldown without one; split across two values, the fleet silently tests two resolvers. lint-repo's setup-uv-version-pin check reports both, non-fatally.
• Inline upstream pin with no cooldown exemption: a run: command pinning the toolkit (uvx 'repomatic==X.Y.Z' …) under a workflow that sets UV_EXCLUDE_NEWER must carry --exclude-newer-package repomatic=P0D on the same command line, since uvx reads no project configuration and the pin routinely names a release published hours ago. Without it the command cannot resolve, and every needs: metadata job dies with it. lint-repo's self-pin-cooldown-exemption check is fatal on this.
• Missing workarounds: e.g., the "Force native ARM64 Python on Windows ARM64" step that sets UV_PYTHON.
• Missing matrix exclusions: e.g., windows-11-arm + Python 3.10 (no native ARM64 build).
• Outdated integration patterns: e.g., a third-party action still in use where upstream replaced it with a repomatic run tool.
• Missing coverage floor: e.g., no report.fail_under under [tool.coverage], so a coverage regression never fails the suite.
• YAML scalar style issues: e.g., run: | where run: > is needed for multi-line single commands.

paths: filters that don't fit the downstream project

Header-only sync inherits the canonical paths: filter verbatim (after repomatic/** substitution). When the project's filesystem layout doesn't match, two outcomes are possible:

• Inherited entries that don't exist locally (e.g., tests/**, uv.lock in a non-Python repo): the trigger never fires for them. Coverage is missing, not noisy. Recommend [tool.repomatic.workflow.ignore-paths] to drop them.
• Locally relevant paths not in the canonical filter (e.g., install.sh, dotfiles/** in a config repo): the trigger silently skips PRs that should run CI. Recommend [tool.repomatic.workflow.extra-paths] to append them globally, or [tool.repomatic.workflow.paths] keyed by filename for a per-workflow wholesale replacement.

The relevant config schema lives in WorkflowConfig (repomatic/config.py): source_paths, extra_paths, ignore_paths, and paths (per-workflow override dict, keyed by workflow filename). Per-workflow override is authoritative — it replaces the entire paths: list and ignores the other knobs.

Excluded workflows

Respect exclude entries from [tool.repomatic] in pyproject.toml. Report excluded files but do not flag them as drift.