consolidate-task_skill

Overview

This skill helps convert a completed task into an Architectural Decision Record (ADR) and manage ADR files under docs/architecture. It reduces task clutter by deciding whether to create, update, or skip an ADR and then generating a properly named ADR file with the required sections. The skill also guides post-save steps like updating the ADR index and archiving the original task folder.

How this skill works

The skill reads the task file at .tasks/{task-folder}/task.md, determines whether the change is an architectural decision or routine work, and selects create/update/skip accordingly. It scans existing docs/architecture/ADR-* files to decide whether to update an ADR or allocate the next ADR number. Finally, it outputs a ready-to-save ADR in the required format and lists follow-up actions (update README, archive task).

When to use it

• A completed task introduces a new architectural pattern or component.
• A task reverses or significantly modifies a prior architectural decision.
• A task establishes new conventions that future developers must follow.
• You need to consolidate decisions and reduce .tasks/ clutter by documenting outcomes.
• You suspect the change affects how the codebase should evolve long-term.

Best practices

• Only create ADRs for true architectural decisions; skip bug fixes, minor features, or routine maintenance.
• Scan existing ADR files first and prefer updating an ADR when the change extends an existing decision.
• Use the ADR-NNN-{decision-name}.md naming convention and increment numbers consistently.
• Keep ADRs high-level: focus on patterns, trade-offs, and the problem solved, not low-level implementation details.
• Include deletions and before/after comparisons to show what was replaced and why.

Example use cases

• Introduce a new unified query execution pattern that other teams should adopt.
• Replace a legacy service with a new interface that changes how modules interact.
• Document a reversal of a prior decision (e.g., monolith -> modular services).
• Add conventions for error handling or data validation across services.
• Summarize a cross-cutting change that affects architecture, like auth or observability.