maintenance

name	maintenance
description	Investigate, adopt, and verify dependency updates for repo-map. Captures what changed, understands why, cross-references against the codebase, applies fixes, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates already applied.
metadata	{"author":"cyanheads","version":"1.0","audience":"project","type":"workflow"}

When to Use

• After running poetry update (or manually bumping a pyproject.toml constraint) and wanting to review the impact (Mode B — typical)
• To run the whole flow end-to-end — outdated check → update → investigate → adopt → verify (Mode A)
• Before tagging a release, to make sure the lockfile and code are coherent

Entry Modes

Mode	Starting Point	First Step
A — Full flow	Lockfile is current; want to update	Step 1
B — Post-update review	User already ran poetry update (and possibly edited pyproject.toml)	Skip to Step 3 with the update output or git diff poetry.lock pyproject.toml

Both modes converge at Step 3 and end at Step 8.

Steps

1. Survey what's outdated (Mode A only)

poetry show --outdated

Columns are name | current | latest | description. Note which jumps cross majors — Poetry's caret constraints (^1.2.3) cap at the next major and poetry update will not cross them. For pre-1.0 packages, a minor bump is effectively a major and requires editing the constraint.

2. Apply the update (Mode A only)

For in-range bumps:

poetry update

For out-of-range jumps (caret-locked majors, pre-1.0 minor crossings), edit the constraint in pyproject.toml first, then poetry update <package>. Alternatively poetry add <package>@latest rewrites the constraint and updates in one step.

Capture the version deltas from stdout (or git diff poetry.lock pyproject.toml) — these feed Step 3.

3. Investigate changelogs

If the changelog skill is available, invoke it with the captured list of updated packages — it resolves repos, fetches release notes between old and new versions, and cross-references against actual imports. Skip the per-package research below if so.

Otherwise, for each updated package:

1. Find the source repo (poetry show <package> shows the homepage; PyPI page links to it)
2. Read CHANGELOG / release notes between old and new version tags
3. Grep src/ for imports of the package and cross-reference against the changes
4. Note: what changed, impact on repo-map, action items

Focus only on packages we actually import from. Transitive bumps (attrs, idna, platformdirs, etc.) usually need no investigation unless they fail at runtime.

The packages that matter for repo-map:

Package	Used In	Why It Matters
aiohttp	llm_service.py	OpenRouter HTTP client; session/timeout/retry semantics
pydantic / pydantic-settings	config.py	Settings loading and validation; v2.x is iterating fast
pathspec	file_scanner.py	.gitignore matching
tqdm	cli_handler.py, logging_utils.py	Progress bars + logging handler
certifi	llm_service.py	TLS bundle; new releases just refresh certs
ruff / black / pytest	dev tooling	New rules / format diffs / test runner changes

4. Adopt changes in the codebase

Apply findings from Step 3. Defaults are cost/benefit — there's no upstream framework here that's authoritative.

• Breaking changes — fix call sites. Not optional.
• Deprecation warnings — migrate now, while context is fresh. Don't silence.
• New ruff rules that flag existing code — fix the code; don't add ignores.
• black format drift — run poetry run python scripts.py format and commit the reformat as a separate concern from code changes if the diff is large.
• New library APIs that supersede local helper code — swap them in if it's a clear win (smaller surface, removed dep, fewer bugs). Skip if marginal.
• New features that don't match existing call sites — note for later, don't refactor speculatively.

5. Verify

poetry run python scripts.py check
poetry build

The test suite includes strict expected-failure reproductions linked to open issues; an unexpected pass is a gate failure until the implementation and issue state are reconciled. Smoke test the actual tool against a small public repository to catch runtime regressions the local tests cannot:

poetry run repo-map /path/to/small/repo -y

Watch for new exceptions, broken parsing, or LLM call failures. Fix anything that fails. Re-run until clean.

6. Sync skills to agent mirrors

skills/ is the canonical source; .agents/skills/ and .claude/skills/ are read-only mirrors that local agent toolchains consume. They drift silently when skills/ is edited.

scripts.py check (Step 5) verifies the mirrors: it fails, naming every missing or content-drifted mirror file, and writes nothing. Regenerating them is a separate, deliberate command:

poetry run python scripts.py sync-skills
# or, no Poetry:
python3 scripts/sync_skills.py

A Claude Code PostToolUse hook (in .claude/settings.json) runs that same mutating sync after any Write/Edit/MultiEdit under skills/, so reported drift usually means skills were authored outside Claude Code.

Neither mode deletes: the sync copies only missing or content-drifted files, and the check reports a mirror-only file as an orphan instead of removing it (those may be general-purpose skills sourced elsewhere).

7. Wrap-up artifacts

Update files that frequently fall out of sync:

File	When
CHANGELOG.md	Always — add an entry under a new version with the dependency bumps and any code adoptions
pyproject.toml version	Bump (patch for dep-only updates, minor if code behavior changed)
AGENTS.md / CLAUDE.md	If a workflow command, env var, or module responsibility changed
README.md	Only if user-facing behavior, defaults, or commands changed (badges are dynamic from PyPI — skip those)

Use a concrete version + date in CHANGELOG.md (e.g. ## [0.7.1] - 2026-04-25) — never [Unreleased].

8. Summary

Present a concise numbered summary to the user:

1. Updated packages — short list with version deltas (N total)
2. Breaking changes handled — call sites fixed
3. Adoptions made — new APIs swapped in, helpers removed
4. Wrap-up artifacts — files updated (CHANGELOG entry, version bump, doc edits)
5. Open decisions — ambiguous items: out-of-range majors that weren't taken, adoptions where the tradeoff is close, deprecation warnings deferred
6. Status — ruff / black / pytest / smoke-test results

Checklist

• Update applied (poetry update or constraint edit + poetry update <pkg>) — Mode A, or already done by user — Mode B
• Per-package changelog investigation done (via changelog skill or manually)
• Adoption opportunities identified and applied
• poetry run python scripts.py check passes
• poetry build succeeds
• Smoke test against a sample repo passes
• skills/ mirrors in sync (the project check fails on drift; run poetry run python scripts.py sync-skills to regenerate them)
• CHANGELOG.md entry added with concrete version + date
• pyproject.toml version bumped
• AGENTS.md / CLAUDE.md / README.md updated if behavior or commands changed
• Numbered summary presented to user