analyse-todos

name	analyse-todos
description	Scan the whole project for improvements in implementation, architecture, API, clarity, refactoring and guideline compliance. Records findings as TODO comments in source or as bullets in the README TODO section.

Scan the project for improvements and record actionable findings.

Goal: a list of concrete code-level and structural improvements. Each finding becomes either a // TODO: comment in source (single-file or localised change) or a bullet in the README ## TODO section (cross-file, architectural or feature-level work). Both placements are valid when a finding has both a local and a broader dimension.

Phase 1: Gather context

Read in full:

• Package.swift and README.md
• All files in Sources/
• All existing // TODO: and // FIXME: comments, noting file and line for each
• AGENTS.md (shared and local) for guidelines

Phase 2: Analyse

Complete the full analysis before presenting anything.

Implementation

• Incorrect or incomplete behavior
• Missing edge-case handling at system boundaries (user input, external APIs)
• Inefficient patterns with a clear better alternative

Architecture

• Coupling between layers that should be separate
• Responsibilities that belong in a different type
• Patterns that will not scale as the package grows

API design

• Names that don't match Swift API Design Guidelines or the project's naming patterns
• Public API that is easy to misuse. Prefer compile-time errors over runtime ones.
• Missing conveniences a consumer would reasonably expect

Clarity

• Code flow that requires significant effort to follow
• Names that obscure intent

Guideline compliance

• Violations of any rule in AGENTS.md (shared and local) not already caught by /check-comments

Existing TODOs

• Is the item still valid, or has it already been resolved?
• Is the text clear enough to act on without reading the surrounding code?
• Is it placed correctly? Source for local changes, README for broader work.
• Should it be promoted from source to the README, or demoted?
• Should it be split into multiple items or merged with a related one?
• Should it be removed entirely: resolved, obsolete or no longer aligned with the design intent?

Phase 3: Present findings

Present findings using the standard format defined in AGENTS.md.

Phase 4: Apply

For source TODOs, insert the comment above the relevant declaration or block. For README entries, append to the ## TODO section, creating it if absent.

When done, suggest running /reflect to capture any process improvements from the session.

Constraints

• Do not fix anything. Only record findings as TODOs.