Add Improvement

Overview

Add a new improvement entry to the improvements tracking document. This skill creates a structured improvement record with a unique ID, progress tracking checkbox, and detailed description section.

Arguments

Definitions

• •[--explore] (optional): When set, analyze the codebase to add additional technical information to the improvement request. Defaults to false.
• •<context> (required): Description of the improvement request. Can include problem description, affected areas, or desired outcome.

Values

$ARGUMENTS

Configuration

The improvements document path is configured via improvementsPath in settings or defaults to agentic/improvements.md.

To override in .claude/configs/agentic-sdlc.json:

{
  "improvementsPath": "custom/path/improvements.md"
}

Core Principles

• •Create the improvements document if it doesn't exist
• •Generate unique improvement IDs using sequential numbering
• •Keep improvement details concise (max 100 lines per entry)
• •Preserve existing improvements when adding new ones
• •Use consistent formatting matching existing entries
• •Use existing ID prefixes when the improvement type is clear (SEC, DEBT, TEST, DOC)
• •Improvement entries should be self-contained and actionable

Instructions

1. •

   Determine File Path

   • •Check for agentic-sdlc.improvementsPath in settings
   • •Default to agentic/improvements.md if not configured
2. •

   Check Document Existence

   • •If the document does not exist, create it with the template structure (see Templates section)
   • •If it exists, read the current content
3. •

   Generate Improvement ID

   • •Scan existing entries to find the highest ID number
   • •Generate next sequential ID in format IMP-XXX (e.g., IMP-007)
   • •Use prefix based on context if clearly identifiable:
     • •SEC-XXX for security-related improvements
     • •DEBT-XXX for technical debt
     • •TEST-XXX for testing improvements
     • •DOC-XXX for documentation improvements
     • •IMP-XXX for general improvements (default)
4. •

   Codebase Analysis (if --explore is set)

   • •Analyze the codebase to identify:
     • •Relevant files and components affected
     • •Existing patterns or implementations related to the improvement
     • •Dependencies or impacts on other parts of the system
   • •Include this technical context in the improvement details
5. •

   Create Improvement Entry

   • •Add checkbox entry to Progress Tracking section: - [ ] ID: Short title
   • •Add detailed section to Improvements List with:
     • •Status: Pending
     • •Problem: Clear description of the issue or opportunity
     • •Files to Investigate: Relevant file paths (if known or discovered via codebase exploration)
     • •Expected Behavior / Goal: What the improvement should achieve
     • •Acceptance Criteria: Measurable criteria for completion
6. •

   Write Updated Document

   • •Preserve all existing content
   • •Insert new checkbox in Progress Tracking section (at the end of the list)
   • •Append new details section to Improvements List
7. •

   Report Result

   • •Output confirmation with the new improvement ID
   • •Show the improvement title and file path

Output Guidance

Return a JSON object summarizing the action taken:

{
  "success": true,
  "improvement_id": "{{improvement_id}}",
  "title": "{{title}}",
  "document_path": "{{document_path}}",
  "explored_codebase": "{{explored}}",
  "files_identified": ["{{files_array}}"]
}

Templates

New Document Template

When creating a new improvements document, use this structure:

# Improvements

This file tracks improvement opportunities identified during code analysis. Each improvement has a checklist entry for progress tracking and a detailed section explaining the issue.

## How to Use This File

1. **Adding Improvements**: Add a checkbox to the Progress Tracking section (`- [ ] IMP-XXX: Short title`) and a corresponding details section with problem description, files to investigate, and acceptance criteria.
2. **Working on Improvements**: Mark the item as in-progress by keeping `[ ]` and update the Status in the details section to "In Progress".
3. **Completing Improvements**: Change `[ ]` to `[x]` and update the Status to "Completed".
4. **Implementation**: Use `/sdlc-plan` to create an implementation plan, then implement the changes.

## Progress Tracking

<!-- Add new items here -->

## Improvements List

List the details of every improvement request, 100 lines maximum per item.

Improvement Entry Template

---

### ID: Short descriptive title

**Status**: Pending

**Problem**: Clear description of the issue or opportunity.

**Files to Investigate**:

- `path/to/file.ts` - Brief note about relevance

**Expected Behavior / Goal**: What the improvement should achieve.

**Acceptance Criteria**:

- [ ] First measurable criterion
- [ ] Second measurable criterion