Accelint Ts Audit All

Audit All

Comprehensive TypeScript file audit system that systematically applies multiple audit skills with progress tracking and interactive approval.

NEVER Do When Running Audits

• NEVER skip the initial test coverage step - Refactoring without test coverage first leads to undetected breakage. Always run accelint-ts-testing before any code changes.
• NEVER run best-practices and performance sequentially - Running them separately creates contradictory recommendations for the same code. Always run in parallel to see merged suggestions.
• NEVER present issues one-by-one for approval - Always show ALL issues in a numbered table first, then display each issue's detailed before/after code, THEN ask for numbered list acceptance. This prevents wildly inconsistent presentations and allows users to spot conflicts across parallel processes.
• NEVER skip displaying the overview table - BLOCKING: You MUST display the emoji severity table with ALL issues before showing any detailed changes. No exceptions.
• NEVER ask for approval before showing all detailed changes - BLOCKING: You MUST show the complete before/after code for EVERY issue before asking "Apply which issues?"
• NEVER auto-apply all recommendations - Each change needs user approval (accept/deny/other) to maintain code ownership and prevent unwanted modifications.
• NEVER run one-off commands instead of documented verification commands - The audit-process file documents EXACT verification commands. Use those commands verbatim. Never improvise with npm test, bun test, or similar unless they match the documented commands exactly.
• NEVER skip saving progress after completing a step - After EVERY step completion, immediately save detailed progress to audit-process file BEFORE moving to next step. Context limits will break otherwise.
• NEVER skip the 100-pass PBT verification - When property-based tests are added, you MUST run the test suite 100 times to verify stability. Random failures are common with PBT. This is a blocking requirement - do not proceed until 100 consecutive passes are achieved. Run the tests without coverage reporting on to increase speed and stability.
• NEVER lose progress when context runs out - Save detailed progress to audit-process file after each step. Context limits are guaranteed in large audits.
• NEVER assume property-based tests are stable - Random test failures are common with PBT. Run new property tests 100 times to verify stability before accepting. Run the tests without coverage reporting on to increase speed and stability.
• NEVER add PERF comments everywhere - Only add // PERF: comments when they provide meaningful insight that future developers wouldn't discover on their own.
• NEVER mark a file complete without all 9 steps - Partial audits leave files in inconsistent states. Complete all steps or mark as in-progress.
• NEVER move on from a broken build - Fix compilation errors, test failures, and lint issues immediately before proceeding to the next step.
• NEVER run audit in main branch - Always create an isolated worktree to prevent conflicts with parallel audits and allow safe experimentation.

Before Starting an Audit, Ask

Apply these tests before launching a comprehensive audit:

Scope Validation

• Is this path valid and accessible? Verify the file or directory exists before creating TODO lists.
• Are there test and build commands available? Check package.json or ask user for verification commands before starting.
• How many files will this audit? Large directories (>5 files) will require multiple sessions. Set expectations upfront.

Session Management

• Is this a new audit or resuming? Check for existing audit-process files in .agents/audit/ before creating new ones.
• Will this fit in one session? Estimate ~1-5 files per session max. Plan for resumption if larger.
• Are verification commands known? Document exact test/build/lint commands in the audit-process file from the start.

Change Philosophy

• What's the user's risk tolerance? Some users want every suggestion, others only critical fixes. Clarify before first interactive prompt.
• Should performance micro-optimizations be included? 1.05x-1.15x gains may not be worth code churn for all projects.

How to Use

This skill creates and maintains an audit process file that tracks progress across sessions. It systematically runs four audit skills on each file with interactive approval.

Workflow Overview

1. Initialize - Create TODO list and audit tracking files 2. For each file - Run 9-step audit process with user approval 3. Track progress - Save after each step to survive context limits 4. Archive completed - Move finished files to history file

Main Audit Workflow

Step 1: Initialize the Audit

Check for existing audit: Look in .agents/audit/ directory (in the original repository root) for existing audit-process files.

Note: Ensure .agents/audit/ is in your project's .gitignore to prevent committing audit tracking files.

If resuming an existing audit, read the audit-process file to understand current status:

1. Check completion status:

• Review "Current Status" section for files completed vs remaining
• Review "Files to Audit" section for pending/completed breakdown
• If all files are marked "Completed", the audit is done

2. Check worktree status (backwards compatibility):

• If "Worktree Information" section exists: verify worktree still exists and switch to it
• If no worktree documented: this is a legacy audit from before worktree support. Continue in current branch without creating a worktree.
• Note: Only NEW audits created after this feature will use worktrees

3. Continue from "Resume Instructions" section

Skip to Step 2 if resuming.

For new audits, create isolated worktree:

BLOCKING: All audit work MUST happen in an isolated worktree to prevent conflicts with parallel audits and allow safe rollback.

1. Create worktree with timestamped branch:

   timestamp=$(date +%Y%m%d-%H%M%S)
   git worktree add .agents/worktrees/audit-${timestamp} -b audit/${timestamp}

2. Switch to the worktree directory:

   cd .agents/worktrees/audit-${timestamp}

3. Log the worktree path - You will work in this directory for the entire audit

Important: The worktree is created in .agents/worktrees/ (not .agents/audit/) to avoid conflicts with the gitignored .agents/audit/ directory where tracking files are stored.

Create tracking files:

MANDATORY - READ ENTIRE FILE: Before creating any tracking files, you MUST read `assets/audit-process-template.md` completely from start to finish to understand the exact format and structure required. NEVER set any range limits when reading this file.

Similarly, you MUST read `assets/audit-history-template.md` to understand the archival format.

Do NOT load these templates again after the initial setup - they are only needed once at the start of a new audit.

Create timestamped tracking files in the ORIGINAL repository (not in the worktree):

• Go back to the original repository root: cd $(git rev-parse --show-toplevel)
• Create .agents/audit/audit-process-${timestamp}.md (use same timestamp as worktree)
• Create .agents/audit/audit-history-${timestamp}.md (same timestamp)
• Return to the worktree: cd .agents/worktrees/audit-${timestamp}

Important: Tracking files live in the original repo's .agents/audit/ directory (which should be gitignored) so they are NOT committed with audit changes.

Build the TODO list:

Find all TypeScript files in the target directory, excluding .test.ts, .spec.ts, and .bench.ts files. If given a single file, validate it's not a test/benchmark file.

Populate the audit-process file:

• Add worktree path and branch to "Worktree Information" section
• Add all files to "Files to Audit" section as "Pending"
• Document the exact verification commands (test/build/lint)
• Set "Current File" to first pending file
• Save the file

Step 2: Audit Each File (8-Step Process)

For each file in the pending list, follow this exact sequence:

Phase 1: Initial Test Coverage

Step 1: Run accelint-ts-testing skill

/skill accelint-ts-testing <file-path>

Step 2: Interactive Changes

BLOCKING - Interactive Approval Required:

You MUST complete all three checkpoints before proceeding:

1. ✅ Display emoji severity table with ALL issues (see "Interactive Change Approval Pattern")

2. ✅ Show detailed before/after code for EVERY issue

3. ✅ Ask "Apply which issues?" with numbered list acceptance

NO EXCEPTIONS. If you skip any checkpoint, you are violating the workflow.

• Apply accepted changes
• BLOCKING REQUIREMENT: If property-based tests added, run verification:

  # Run test suite 100 times to verify PBT stability
  for i in {1..100}; do <test-command> || break; done

• Run the tests without coverage reporting to prevent coverage conflicts
• If ANY run fails, examine the seed that failed
• Fix test properties (add constraints to arbitraries: date ranges, filtered NaNs, safe strings)
• Re-run 100 times until 100 consecutive passes achieved
• DO NOT proceed to Step 3 until this verification passes
• Document findings in "Current File - Detailed Progress" section
• Update status to show Step 1 ✅, Step 2 ✅
• SAVE PROGRESS to audit-process file NOW before continuing

Phase 2: Code Quality & Performance Analysis

Step 3: Run BOTH skills in parallel

CRITICAL: Run these together to avoid contradictory suggestions:

/skill accelint-ts-best-practices <file-path>
/skill accelint-ts-performance <file-path>

Step 4: Interactive Changes

• Review both sets of recommendations
• If recommendations overlap:
• Try to merge them into single fix if possible
• If conflicting, present both and let user choose

BLOCKING - Interactive Approval Required:

You MUST complete all three checkpoints before proceeding:

1. ✅ Display emoji severity table with ALL issues from BOTH skills (see "Interactive Change Approval Pattern")

2. ✅ Show detailed before/after code for EVERY issue

3. ✅ Ask "Apply which issues?" with numbered list acceptance

NO EXCEPTIONS. If you skip any checkpoint, you are violating the workflow.

• Apply accepted changes
• Add // PERF: comments only where they add genuine insight
• Document in "Current File - Detailed Progress"
• Update status to show Step 3 ✅, Step 4 ✅
• SAVE PROGRESS to audit-process file NOW before continuing

Phase 3: Verify Changes

Step 5: Run verification commands

⚠️ CRITICAL: Use EXACT commands from audit-process file "Verification Commands" section. DO NOT improvise or run one-off commands.

Run ALL verification commands documented in audit-process file:

# Example commands (MUST match audit-process file exactly):
cd <project-root>; npm test
cd <project-root>; npm run build
cd <project-root>; npm run lint

Step 6: Interactive Changes (if needed)

If verification passes, skip to documenting results. Otherwise:

BLOCKING - Interactive Approval Required:

You MUST complete all three checkpoints before proceeding:

1. ✅ Display emoji severity table with ALL verification failures (see "Interactive Change Approval Pattern")

2. ✅ Show detailed before/after code for EVERY issue

3. ✅ Ask "Apply which fixes?" with numbered list acceptance

NO EXCEPTIONS. If you skip any checkpoint, you are violating the workflow.

• Apply accepted changes
• Document results in "Current File - Detailed Progress"
• Update status to show Step 5 ✅, Step 6 ✅
• SAVE PROGRESS to audit-process file NOW before continuing

Phase 4: Documentation

Step 7: Run accelint-ts-documentation skill

/skill accelint-ts-documentation <file-path>

Step 8: Interactive Changes

BLOCKING - Interactive Approval Required:

You MUST complete all three checkpoints before proceeding:

1. ✅ Display emoji severity table with ALL documentation issues (see "Interactive Change Approval Pattern")

2. ✅ Show detailed before/after code for EVERY issue

3. ✅ Ask "Apply which issues?" with numbered list acceptance

NO EXCEPTIONS. If you skip any checkpoint, you are violating the workflow.

• Apply accepted changes
• Run final verification to ensure docs didn't break anything (use EXACT commands from audit-process file)
• Document in "Current File - Detailed Progress"
• Update status to show Step 7 ✅, Step 8 ✅
• SAVE PROGRESS to audit-process file NOW before continuing to Step 3 (Archive)

Step 3: Archive Completed File

When all 9 steps complete for a file:

1. Move detailed progress to history file

• Copy entire "Current File - Detailed Progress" section
• Append to audit-history file
• Add summary statistics at end of file's section

2. Update audit-process file

• Mark file as "Completed" in "Files to Audit" section
• Clear "Current File - Detailed Progress" section
• Set "Current File" to next pending file
• Update "Resume Instructions" for next file
• Update "Current Status" counts

3. Save both files

Step 4: Continue or Complete

If more pending files exist:

• Return to Step 2 for next file
• Monitor context usage - if approaching limit, stop and save progress

If all files completed:

1. Run final verification in worktree:

• Run final full test suite + lint verification
• Ensure all changes pass before merging

2. Merge worktree back to original branch:

   # Extract timestamp from current worktree directory name
   # We're in .agents/worktrees/audit-YYYYMMDD-HHMMSS
   timestamp=$(basename $(pwd) | sed 's/audit-//')

   # Get the original branch from this audit's process file (in original repo)
   repo_root=$(git rev-parse --show-toplevel)
   audit_process_file="${repo_root}/.agents/audit/audit-process-${timestamp}.md"
   original_branch=$(grep "^**Original Branch:**" ${audit_process_file} | cut -d'`' -f2)

   # Commit all changes in worktree
   git add -A
   git commit -m "refactor: complete TypeScript audit

   - Improved test coverage across all files
   - Applied type safety and best practice improvements
   - Optimized performance where beneficial
   - Enhanced documentation

   Co-Authored-By: {current_model}"

   # Switch back to original branch
   cd "${repo_root}"
   git checkout ${original_branch}

   # Merge the audit branch
   git merge --no-ff audit/${timestamp}

3. Clean up worktree:

   # Remove the worktree (use the timestamp extracted earlier)
   git worktree remove .agents/worktrees/audit-${timestamp}

   # Optionally delete the audit branch
   git branch -d audit/${timestamp}

4. Update audit-process file with completion:

• Add completion summary with total statistics
• Document merge commit hash
• Mark audit as "✅ COMPLETE - Merged to ${original_branch}"

5. Report results:

• Total statistics across all files
• Merge commit information
• Confirmation that worktree was cleaned up

Progress Tracking Format

File Status Markers:

• [ ] - Pending (not started)
• [x] - Completed (all 9 steps done, moved to history)

Step Status Markers:

• ✅ - Complete
• 🔄 - In Progress
• ⏸️ - Pending (not started)

Detailed Progress Template:

### filename.ts - Audit Status 🔄 IN PROGRESS

**Overall Progress:** X% complete (Step Y of 8)

#### ✅ Step 1: Test Coverage - COMPLETE
[Findings, changes applied, test results]

#### 🔄 Step 2: Interactive Changes - IN PROGRESS
[Current change being reviewed, user decision needed]

#### ⏸️ Step 3: Code Quality Analysis - PENDING
[Not started yet]

Interactive Change Approval Pattern

CRITICAL: Always use the two-phase presentation pattern. NEVER present issues one-by-one or ask for approval before showing all changes.

Phase 1: Overview Table (Quick Scan)

Present ALL issues in a numbered table using emoji severity indicators:

## Found Issues Summary (X total)

| # | Severity | Type | Lines | Description |
|---|----------|------|-------|-------------|
| 1 | 🛑 Critical | Type Safety | 45-47 | Missing null check on user object |
| 2 | ⚠️ High | Performance | 89 | N+1 query in loop - use batch fetch |
| 3 | ⚡ Medium | Performance | 120-125 | Filter+map → single pass with reduce |
| 4 | 🔵 Low | Best Practice | 78 | Use const assertion for readonly array |
| 5 | ✅ Info | Documentation | 12 | Missing JSDoc return type |

Severity Legend:

• 🛑 Critical - Causes runtime errors, security vulnerabilities, or data loss
• ⚠️ High - Type errors, significant performance issues, or API breaking changes
• ⚡ Medium - Moderate performance gains, maintainability improvements
• 🔵 Low - Minor optimizations, style improvements
• ✅ Info - Documentation, comments, non-functional improvements

Phase 2: Detailed Changes (Full Context)

After showing the overview table, display each issue with complete before/after code:

---

### Issue #1: Missing null check (🛑 Critical - Type Safety)
**Lines:** 45-47
**Problem:** Function doesn't handle null user case
**Impact:** Runtime TypeError when user is null

❌ **Before:**

function getUsername(user: User | null) { return user.name; // TS error + runtime crash }

✅ **After:**

function getUsername(user: User | null) { return user?.name ?? 'Anonymous'; }

**Expected Benefit:** Prevents runtime TypeError, fixes TS compilation error

---

### Issue #2: N+1 Query Performance (⚠️ High - Performance)
[... same detailed format for each issue ...]

---

### Issue #3: Filter+map optimization (⚡ Medium - Performance)
[... same detailed format for each issue ...]

---

[Continue for all issues...]

---

**Apply which issues?** Enter numbers (e.g., "1, 2, 5" or "all" or "skip"):

Key Benefits:

• Overview table allows quick scanning for conflicts across parallel processes
• Numbered list makes acceptance explicit and trackable
• All code changes shown upfront before any approval
• Emoji severity indicators enable instant visual prioritization
• Consistent format prevents wildly varying presentations

Wait for user response with numbered list before applying any changes.

Verification Commands

The audit-process file MUST document exact verification commands. Common patterns:

Node.js projects:

cd <project-root>; npm test
cd <project-root>; npm run build
cd <project-root>; npm run lint

Bun projects:

cd <project-root>; bun run test
cd <project-root>; bun run build
cd <project-root>; bun run lint
cd <project-root>; bun run bench  # if applicable

Monorepo packages:

cd <workspace-root>/packages/<package-name>; npm test

Always use the EXACT commands from the audit-process file. Never guess.

Important Notes

• Do NOT load README.md - It contains user-facing documentation that duplicates this file. All Agent instructions are contained in SKILL.md.
• Worktree location: All audit work happens in .agents/worktrees/audit-${timestamp} to avoid conflicts with the gitignored .agents/audit/ directory.
• Tracking files location: Audit process and history files are stored in the original repository's .agents/audit/ directory (gitignored) and are NOT committed with audit changes.
• Property-based test stability: If property tests fail randomly, check the exact seed that failed and verify the fix against that seed. Add constraints to arbitraries (date ranges, filtered NaNs, safe strings) to prevent false positives.
• Parallel skill execution: When running ts-best-practices and ts-performance in parallel, wait for BOTH to complete before presenting recommendations. This allows you to identify and merge overlapping suggestions.
• Context window management: Audit-process files are designed to survive context limits. After completing each step, save progress. If you must stop mid-file, document exactly which step you're on and what the next action should be.
• Build failures block progress: Never proceed to the next step if verification commands fail. Fix the issue or roll back the change first.
• PERF comment guidelines: Only add performance comments when the optimization is non-obvious. "Using for...of instead of map" doesn't need a comment. "Memoizing deserializer to avoid repeated JSON parsing" does.
• History file is write-only: Only read audit-history file if you need to understand a previous decision or consider reverting a change. Otherwise, it's purely archival.

{Directory Name} Audit History

Archive of completed file audits for reference only.

⚠️ Note: This file contains historical context from completed audits. Only read this if you need to understand previous decisions or revert changes.

---

Completed Files - Detailed Progress

filename.ts - Audit Status ✅ COMPLETE

Overall Progress: 100% complete (All 9 steps finished)

✅ Step 1: Test Coverage - COMPLETE

Configuration: ✅ Mock cleanup properly configured (clearMocks: true, restoreMocks: true)

Issues Found: X total (breakdown by severity)

1. Issue 1 (Severity): [Description] - Line(s) X

• Problem: [What was wrong]
• Impact: [Why it mattered]
• Fix Applied: ✅/❌ [What was done]

Result: ✅ All X tests passing

✅ Step 2: Interactive Changes - COMPLETE

[Summary of what changes were applied or skipped]

✅ Step 3: Code Quality Analysis - COMPLETE

Best Practices Findings: [Summary]

Issues Found: X total (breakdown by severity)

1. Issue 1 (Severity): [Description] - Line(s) X

• Problem: [What was wrong]
• Impact: [Type Safety / Maintainability / etc.]
• Fix Applied: ✅/❌ [What was done]

Performance Findings: [Summary]

Issues Found: X total (breakdown by severity)

1. Issue 1 (Severity): [Description] - Line(s) X

• Problem: [What was wrong]
• Expected Gain: [Performance improvement estimate]
• Fix Applied: ✅/❌ [What was done]

✅ Step 4: Interactive Changes - COMPLETE

[Summary of what changes were applied or skipped]

Result: ✅ All tests passing | Build successful

✅ Step 5: Verify Changes - COMPLETE

Ran full test suite to verify all changes are working:

• ✅ All X tests passing | Y skipped
• ✅ No type errors
• ✅ Duration: X.XXs

✅ Step 6: Interactive Changes - COMPLETE

[Summary - usually "No additional changes needed from verification"]

✅ Step 7: Documentation Pass - COMPLETE

Documentation Findings: [Summary]

Issues Found: X total (breakdown by priority)

1. Issue 1 (Priority): [Description] - Line X

• Problem: [What was wrong]
• Impact: [API clarity / IDE tooling / etc.]
• Fix Applied: ✅/❌ [What was done]

Assessment: [Overall documentation quality assessment]

✅ Step 8: Interactive Changes - COMPLETE

[Summary of what changes were applied or skipped]

Final Verification: ✅ All tests passing | Build successful | Lint passing

📊 Summary Statistics

• Total fixes applied: X (breakdown by category)
• Test improvements: X (specific improvements)
• Type safety improvements: X (specific improvements)
• Performance improvements: X (specific improvements with expected gains)
• Documentation fixes: X (specific improvements)
• Tests: All X passing throughout audit
• Code quality: [Overall assessment]

---

<!-- Additional completed files follow the same format -->

{Directory Name} Audit Process

Directory: {full/path/to/directory} Started: {YYYY-MM-DD} Last Updated: {YYYY-MM-DD}

---

Worktree Information

Original Branch: {branch-name}

All audit work happens in an isolated worktree (derived from this file's timestamp) to prevent conflicts with parallel audits. When complete, changes will be merged back to the original branch.

---

Audit Process Overview

For each code file, you MUST follow this sequence:

1. Initial Test Coverage - Run accelint-ts-testing to ensure good test coverage exists before refactoring 2. Interactive Changes - Use two-phase pattern: show ALL issues in numbered table with emoji severity (🛑⚠️⚡🔵✅), display detailed before/after for each, accept via numbered list. If PBTs added, MUST run test suite 100 times and achieve 100 consecutive passes before proceeding. Run with tests with coverage disabled. SAVE PROGRESS after this step. 3. Code Quality Analysis - Run accelint-ts-best-practices AND accelint-ts-performance in parallel to avoid contradictory suggestions 4. Interactive Changes - Use two-phase pattern with numbered table. If quality and performance recommendations overlap: merge if possible, otherwise present both and let user choose. Include // PERF: comments only where they add genuine insight. SAVE PROGRESS after this step. 5. Verify Changes - Run EXACT verification commands from "Verification Commands" section below (NEVER improvise) 6. Interactive Changes (if needed) - Use two-phase pattern if verification fails. SAVE PROGRESS after this step. 7. Documentation Pass - Run accelint-ts-documentation to complete the audit 8. Interactive Changes - Use two-phase pattern with numbered table. SAVE PROGRESS after this step before archiving.

Progress Tracking:

• After each step, save detailed progress to the "Current File - Detailed Progress" section in this file
• When a file is complete (all 9 steps done), move its detailed progress to audit-history-{same date as audit-process file}-{same time as audit-process file}.md
• Update the file status in the "Files to Audit" section (Pending → In Progress → Completed)

---

Files to Audit ({total} total)

Pending ({count})

• [ ] file1.ts
• [ ] file2.ts
• [ ] file3.ts

In Progress (0)

Completed (0)

Note: Detailed progress for completed files is archived in audit-history-{timestamp}.md. Only read that file if you need to understand previous decisions or revert changes.

---

Resume Instructions for Next Session

Next File: {filename.ts} (first in pending list)

Process:

# Step 1: Test coverage analysis
/skill accelint-ts-testing {path/to/file.ts}

# Step 2: Apply user-selected test improvements

# Step 3: Analyze code quality (run both in parallel)
/skill accelint-ts-best-practices {path/to/file.ts}
/skill accelint-ts-performance {path/to/file.ts}

# Step 4: Apply changes interactively with user approval

# Step 5: Verify with tests
{exact test command}
{exact build command}

# Step 6: Apply changes interactively with user approval (if needed)

# Step 7: Documentation pass
/skill accelint-ts-documentation {path/to/file.ts}

# Step 8: Apply changes interactively with user approval

# Step 9: Final verification
{exact lint command}

---

Notes

File Organization

• In-progress work → Document in "Current File - Detailed Progress" section of this file
• Completed work → Move to audit-history.md when all 9 steps are done
• Historical reference → Only read audit-history.md if you need to revert or understand past decisions

Audit Guidelines

• Test files (.test.ts) and benchmark files (.bench.ts) are excluded from this audit
• ALWAYS use two-phase interactive pattern: Show ALL issues in emoji severity table first, then detailed before/after for each, then accept via numbered list. NEVER present one-by-one.
• Performance comments (// PERF:) should only be added when they provide meaningful insight
• User must approve each change before applying (numbered list acceptance workflow)
• BLOCKING: Save progress to this file after completing EACH step before continuing
• This audit will require multiple sessions due to context window constraints
• BLOCKING: If property-based tests are added, run test suite 100 times and achieve 100 consecutive passes before proceeding. Random failures are common with PBT.
• If ANY run fails, examine the seed that failed
• Fix test properties (add constraints to arbitraries: date ranges, filtered NaNs, safe strings)
• Re-run 100 times until 100 consecutive passes achieved
• Use EXACT verification commands from "Verification Commands" section - NEVER improvise or run one-off commands

---

Verification Commands

You MUST run the provided commands exactly when they are needed:

• Test changes: {exact test command}
• Verify build/check tsc types: {exact build command}
• Test benches (±0.05x is acceptable variance): {exact bench command} (if applicable)
• Verify correct formatting: {exact lint command}

---

Current Status

Ready for: {filename.ts} (next file in pending list) Files Completed: 0 of {total} (0%) Files Remaining: {total}

---

Current File - Detailed Progress

IMPORTANT: Use this section to track in-progress work. When a file is completed, move its detailed progress to audit-history.md.

Current File: None (ready to start {filename.ts}) Status: Not started

<!-- When you start working on a file, replace the above with detailed step-by-step progress like:

filename.ts - Audit Status 🔄 IN PROGRESS

Overall Progress: X% complete (Step Y of 8)

✅ Step 1: Test Coverage - COMPLETE

[Details of findings and changes]

🔄 Step 2: Interactive Changes - IN PROGRESS

[Current status and what needs to happen next]

⏸️ Step 3: Code Quality Analysis - PENDING

[Not started yet]

etc.

-->

JavaScript and TypeScript Audit All

Comprehensive JavaScript and TypeScript file audit system that systematically applies multiple audit skills with progress tracking and interactive approval.

Overview

accelint-ts-audit-all is a meta-skill that orchestrates four specialized JavaScript and TypeScript audit skills (accelint-ts-testing, accelint-ts-best-practices, accelint-ts-performance, accelint-ts-documentation) in a systematic 9-step process. It maintains detailed progress tracking across sessions and requires interactive approval for all changes.

Key Features:

• 🔄 9-step audit process per file with progress tracking
• 🤝 Interactive change approval (accept/deny/other)
• 📊 Parallel execution of quality + performance to avoid contradictions
• 💾 Session persistence with audit-process and audit-history files
• ✅ Comprehensive verification between steps

Installation

npm

npx skills add https://github.com/gohypergiant/agent-skills --skill accelint-ts-audit-all

pnpm

pnpm dlx skills add https://github.com/gohypergiant/agent-skills --skill accelint-ts-audit-all

Usage

This is a command-only skill with no natural triggers. Invoke explicitly with a file or directory path:

/skill accelint-ts-audit-all path/to/file.ts

Or for an entire directory:

/skill accelint-ts-audit-all path/to/src

If you don't provide a path, the skill will ask for one.

What It Does

For each TypeScript file (excluding .test.ts, .spec.ts, .bench.ts), the skill runs this 9-step process:

Phase 1: Initial Test Coverage

1. Run accelint-ts-testing to check test quality 2. Interactively apply test improvements

Phase 2: Code Quality & Performance

3. Run accelint-ts-best-practices AND accelint-ts-performance in parallel 4. Interactively apply improvements (merging overlapping recommendations)

Phase 3: Verification

5. Run test/build/lint commands to verify changes 6. Fix any issues that arise

Phase 4: Documentation

7. Run accelint-ts-documentation to improve code comments 8. Interactively apply documentation fixes

Progress Tracking:

• Creates .agents/audit/audit-process-{date}-{time}.md to track in-progress work
• Creates .agents/audit/audit-history-{date}-{time}.md to archive completed files
• Survives context window limits by saving after each step

Example Session

Initial invocation:

User: /skill accelint-ts-audit-all packages/core/src
Agent: Found 15 TypeScript files to audit. Creating audit tracking files...
       Starting with `utils.ts`...

       **Step 1: Test Coverage Analysis**

       Issue 1 (High): Loose assertion on line 42
       ❌ expect(result).toBeTruthy()
       ✅ expect(result).toBe(true)

       Options: 1) Accept 2) Deny 3) Other
User: 1
Agent: Applied. Running verification...
       ✅ All 150 tests passing

       **Step 3: Code Quality & Performance**
       [Runs both skills, presents merged recommendations...]

Resuming later:

User: /skill accelint-ts-audit-all packages/core/src
Agent: Found existing audit at .agents/audit/audit-process-2026-02-14-143022.md
       Resuming from: validation.ts (file 8 of 15)
       Last completed: Step 4 - Interactive Changes
       Next: Step 5 - Verify Changes

What's Included

• SKILL.md - Main workflow and audit process documentation
• assets/audit-process-template.md - Template for tracking in-progress audits
• assets/audit-history-template.md - Template for archiving completed audits

Requirements

This skill requires these other skills to be installed:

• accelint-ts-testing - Test coverage and quality analysis
• accelint-ts-best-practices - Code quality and type safety checks
• accelint-ts-performance - Performance optimization analysis
• accelint-ts-documentation - JSDoc and comment quality

Verification Commands: Your project needs test/build/lint commands. The skill will ask for exact commands on first run:

• Test command (e.g., npm test, bun run test)
• Build command (e.g., npm run build, tsc)
• Lint command (e.g., npm run lint, biome check)

Design Philosophy

This skill embodies these principles:

1. Interactive Ownership - Every change requires user approval to maintain code ownership and prevent unwanted modifications 2. Progressive Context - Detailed progress tracking allows audits to span multiple sessions without losing state 3. Parallel Analysis - Running quality + performance skills together prevents contradictory recommendations on the same code 4. Verification First - Test coverage check before refactoring, verification after changes, ensures safety 5. Complete or In-Progress - Files are either fully audited (all 9 steps) or marked in-progress, never partially done with no record

Common Scenarios

Large Directory Audit

For directories with >20 files, expect multiple sessions:

• The skill saves progress after each step
• Context window limits will naturally pause the audit
• Resume by re-invoking with the same directory path
• Progress files track exactly where to continue

Property-Based Test Failures

If property-based tests fail randomly:

• Note the exact seed that failed
• Add constraints to arbitraries (date ranges, NaN filtering)
• Run tests 100 times to verify stability
• Document any constraints in test comments

Overlapping Recommendations

When quality + performance suggest changes to same code:

• Skill attempts to merge into single fix
• If conflicting, presents both options
• User chooses which to apply
• Decision documented in audit history

Build Failures After Changes

If verification fails after applying changes:

• Progress stops (won't move to next step)
• User can revert, modify, or debug
• Once fixed, continue from current step
• All verification results documented

Learn More

• SKILL.md - Detailed workflow and instructions
• ts-testing - Test quality skill
• ts-best-practices - Code quality skill
• ts-performance - Performance skill
• ts-documentation - Documentation skill