checklist-generator

Quality Checklist Generator

Overview

Generate comprehensive, context-aware quality checklists combining IEEE 1028 standards (80-90%) with LLM-generated contextual items (10-20%). Ensures systematic quality validation before completion.

Core principle: Universal quality standards enhanced with project-specific context.

When to Use

Always:

• Before completing implementation tasks
• During code review
• QA validation phase
• Pre-commit verification
• Before marking tasks complete

Exceptions:

• Throwaway prototypes
• Configuration-only changes

Purpose

1. IEEE 1028 Base: Proven quality review standards (universal)
2. Contextual Enhancement: LLM adds project-specific items
3. Systematic Validation: Ensures comprehensive quality coverage

IEEE 1028 Base Categories

The following categories are included in every checklist (80-90% of items):

Code Quality

• Code follows project style guide
• No code duplication (DRY principle)
• Cyclomatic complexity < 10 per function
• Functions have single responsibility
• Variable names are clear and descriptive
• Magic numbers replaced with named constants
• Dead code removed

Testing

• Tests written first (TDD followed)
• All new code has corresponding tests
• Tests cover edge cases and error conditions
• Test coverage ≥ 80% for new code
• Integration tests for multi-component interactions
• Tests are isolated and don't depend on order

Security

• Input validation on all user inputs
• No SQL injection vulnerabilities
• No XSS vulnerabilities
• Sensitive data encrypted at rest and in transit
• Authentication and authorization checks present
• No hardcoded secrets or credentials
• OWASP Top 10 considered

Performance

• No obvious performance bottlenecks
• Database queries optimized (no N+1 queries)
• Appropriate caching used
• Resource cleanup (close connections, release memory)
• No infinite loops or recursion risks
• Large data operations paginated

Documentation

• Public APIs documented
• Complex logic has explanatory comments
• README updated if needed
• CHANGELOG updated
• Breaking changes documented
• Architecture diagrams updated if structure changed

Error Handling

• All error conditions handled
• User-friendly error messages (4xx for user errors)
• Detailed logs for debugging (5xx for system errors)
• No swallowed exceptions
• Graceful degradation implemented
• Rollback procedures for failures

Contextual Addition Logic

The skill analyzes the current project context to add 10-20% contextual items:

Detection Strategy

1. Read project files to identify:

   • Framework (React, Vue, Angular, Next.js, FastAPI, etc.)
   • Language (TypeScript, Python, Go, Java, etc.)
   • Patterns (REST API, GraphQL, microservices, monolith)
   • Infrastructure (Docker, Kubernetes, serverless)

2. Generate contextual items based on findings:

TypeScript Projects:

• [AI-GENERATED] TypeScript types exported properly
• [AI-GENERATED] No any types unless justified with comment
• [AI-GENERATED] Strict null checks satisfied

React Projects:

• [AI-GENERATED] Components use proper memo/useCallback
• [AI-GENERATED] No unnecessary re-renders (React DevTools checked)
• [AI-GENERATED] Hooks follow Rules of Hooks
• [AI-GENERATED] Accessibility attributes (aria-*) on interactive elements

API Projects:

• [AI-GENERATED] Rate limiting implemented
• [AI-GENERATED] API versioning strategy followed
• [AI-GENERATED] OpenAPI/Swagger docs updated
• [AI-GENERATED] Request/response validation with schemas

Database Projects:

• [AI-GENERATED] Migration scripts reversible
• [AI-GENERATED] Indexes added for query performance
• [AI-GENERATED] Database transactions used appropriately
• [AI-GENERATED] Connection pooling configured

Python Projects:

• [AI-GENERATED] Type hints on all public functions
• [AI-GENERATED] Docstrings follow Google/NumPy style
• [AI-GENERATED] Virtual environment requirements.txt updated

Mobile Projects:

• [AI-GENERATED] Offline mode handled gracefully
• [AI-GENERATED] Battery usage optimized (no constant polling)
• [AI-GENERATED] Data usage minimized (compression, caching)
• [AI-GENERATED] Platform-specific features tested

DevOps/Infrastructure:

• [AI-GENERATED] Infrastructure as code (Terraform, CloudFormation)
• [AI-GENERATED] Monitoring and alerting configured
• [AI-GENERATED] Backup and disaster recovery tested
• [AI-GENERATED] Security groups/firewall rules minimal access

Output Format

Checklists are returned as markdown with checkboxes:

# Quality Checklist

Generated: {timestamp}
Context: {detected frameworks/languages}

## Code Quality (IEEE 1028)

- [ ] Code follows project style guide
- [ ] No code duplication
- [ ] Cyclomatic complexity < 10

## Testing (IEEE 1028)

- [ ] Tests written first (TDD followed)
- [ ] Test coverage ≥ 80%
- [ ] Tests cover edge cases

## Security (IEEE 1028)

- [ ] Input validation on all user inputs
- [ ] No hardcoded secrets
- [ ] OWASP Top 10 considered

## Performance (IEEE 1028)

- [ ] No obvious performance bottlenecks
- [ ] Database queries optimized
- [ ] Appropriate caching used

## Documentation (IEEE 1028)

- [ ] Public APIs documented
- [ ] README updated if needed
- [ ] CHANGELOG updated

## Error Handling (IEEE 1028)

- [ ] All error conditions handled
- [ ] User-friendly error messages
- [ ] Detailed logs for debugging

## Context-Specific Items (AI-Generated)

{Detected: TypeScript + React + REST API}

- [ ] [AI-GENERATED] TypeScript types exported properly
- [ ] [AI-GENERATED] React components use proper memo
- [ ] [AI-GENERATED] API rate limiting implemented
- [ ] [AI-GENERATED] OpenAPI docs updated

---

**Total Items**: {count}
**IEEE Base**: {ieee_count} ({percentage}%)
**Contextual**: {contextual_count} ({percentage}%)

Usage

Basic Invocation

Skill({ skill: 'checklist-generator' });

This will:

1. Analyze current project context
2. Load IEEE 1028 base checklist
3. Generate contextual items (10-20%)
4. Return combined markdown checklist

With Specific Context

// Provide explicit context
Skill({
  skill: 'checklist-generator',
  args: 'typescript react api',
});

Integration with QA Workflow

// Part of QA validation
Skill({ skill: 'checklist-generator' });
// Use checklist for systematic validation
Skill({ skill: 'qa-workflow' });

Integration Points

QA Agent

The qa agent uses this skill for validation:

1. Generate checklist at task start
2. Validate each item systematically
3. Report checklist completion status

Verification-Before-Completion

Used as pre-completion gate:

1. Generate checklist before marking task complete
2. Ensure all items verified
3. Block completion if critical items fail

Code-Reviewer Agent

Used during code review:

1. Generate checklist for PR
2. Check each item against changes
3. Comment on missing items

Context Detection Algorithm

1. Read package.json or requirements.txt or go.mod
   → Extract dependencies

2. Glob for framework-specific files:
   - React: **/*.jsx, **/*.tsx, package.json with "react"
   - Vue: **/*.vue, package.json with "vue"
   - Next.js: next.config.js, app/**, pages/**
   - FastAPI: **/main.py with "from fastapi"
   - Django: **/settings.py, **/models.py

3. Analyze imports/dependencies:
   - TypeScript: tsconfig.json
   - GraphQL: **/*.graphql, **/*.gql
   - Docker: Dockerfile, docker-compose.yml
   - Kubernetes: **/*.yaml in k8s/ or manifests/

4. Generate contextual items based on detected stack
5. Mark all generated items with [AI-GENERATED]

Example: TypeScript + React + API Project

Input Context:

• package.json contains: "react": "^18.0.0", "typescript": "^5.0.0"
• Files include: src/components/*.tsx, src/api/*.ts

Generated Checklist:

# Quality Checklist

Generated: 2026-01-28 10:30:00
Context: TypeScript, React, REST API

## Code Quality (IEEE 1028)

- [ ] Code follows project style guide
- [ ] No code duplication
- [ ] Cyclomatic complexity < 10
- [ ] Functions have single responsibility
- [ ] Variable names clear and descriptive
- [ ] Magic numbers replaced with constants
- [ ] Dead code removed

## Testing (IEEE 1028)

- [ ] Tests written first (TDD)
- [ ] All new code has tests
- [ ] Tests cover edge cases
- [ ] Test coverage ≥ 80%
- [ ] Integration tests present
- [ ] Tests isolated (no order dependency)

## Security (IEEE 1028)

- [ ] Input validation on all inputs
- [ ] No SQL injection risks
- [ ] No XSS vulnerabilities
- [ ] Sensitive data encrypted
- [ ] Auth/authz checks present
- [ ] No hardcoded secrets
- [ ] OWASP Top 10 reviewed

## Performance (IEEE 1028)

- [ ] No performance bottlenecks
- [ ] Database queries optimized
- [ ] Caching used appropriately
- [ ] Resource cleanup (connections)
- [ ] No infinite loop risks
- [ ] Large data paginated

## Documentation (IEEE 1028)

- [ ] Public APIs documented
- [ ] Complex logic has comments
- [ ] README updated
- [ ] CHANGELOG updated
- [ ] Breaking changes documented

## Error Handling (IEEE 1028)

- [ ] All errors handled
- [ ] User-friendly error messages
- [ ] Detailed logs for debugging
- [ ] No swallowed exceptions
- [ ] Graceful degradation
- [ ] Rollback procedures

## TypeScript (AI-Generated)

- [ ] [AI-GENERATED] Types exported from modules
- [ ] [AI-GENERATED] No `any` types (justified if used)
- [ ] [AI-GENERATED] Strict null checks satisfied
- [ ] [AI-GENERATED] Interfaces prefer over types

## React (AI-GENERATED)

- [ ] [AI-GENERATED] Components use React.memo appropriately
- [ ] [AI-GENERATED] Hooks follow Rules of Hooks
- [ ] [AI-GENERATED] No unnecessary re-renders
- [ ] [AI-GENERATED] Keys on list items

## REST API (AI-GENERATED)

- [ ] [AI-GENERATED] Rate limiting implemented
- [ ] [AI-GENERATED] API versioning in URLs
- [ ] [AI-GENERATED] Request/response validation
- [ ] [AI-GENERATED] OpenAPI/Swagger updated

---

**Total Items**: 38
**IEEE Base**: 30 (79%)
**Contextual**: 8 (21%)

Best Practices

DO

• Start with IEEE 1028 base (universal quality)
• Analyze project context before generating
• Mark all LLM items with [AI-GENERATED]
• Keep contextual items focused (10-20%)
• Return actionable checklist (not generic advice)

DON'T

• Generate checklist without context analysis
• Exceed 20% contextual items (dilutes IEEE base)
• Forget [AI-GENERATED] prefix
• Include items that can't be verified
• Make checklist too long (>50 items)

Iron Laws

1. NEVER complete a task without checklist validation — use verification-before-completion to enforce this gate; skipping checklist validation defeats the entire purpose of the skill.
2. ALWAYS analyze project context before generating the checklist — detect framework, language, and patterns first; a generic checklist without context misses stack-specific items and includes irrelevant ones.
3. NEVER exceed 50 checklist items — checklists longer than 50 items are not completed in practice; be ruthlessly selective and prioritize blocking items over nice-to-haves.
4. ALWAYS mark LLM-generated items with [AI-GENERATED] prefix — IEEE 1028 base items are verified standards; AI-generated items are contextual suggestions requiring human judgment.
5. NEVER include non-verifiable items — every checklist item must be objectively checkable with a yes/no answer; vague items like "code is clean" cannot be definitively validated.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Generating without context analysis	Produces generic, irrelevant checklist items	Detect framework/language/patterns first
Exceeding 50 items	Long checklists are abandoned mid-review	Cut ruthlessly; keep to ≤50 high-value items
No [AI-GENERATED] prefix on contextual items	Conflates standards with suggestions	Mark all AI-contextual items clearly
Non-verifiable items ("code is clean")	Can't be definitively checked off	Only include objectively pass/fail items
Skipping checklist for "small" changes	Small changes introduce large bugs	Apply checklist proportionally for every change

Related Skills

• qa-workflow - Systematic QA validation with fix loops
• verification-before-completion - Pre-completion gate
• tdd - Test-driven development (testing checklist items)
• security-architect - Security-specific validation

Assigned Agents

This skill is used by:

• qa - Quality assurance validation
• developer - Pre-completion checks
• code-reviewer - Code review criteria

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

Check for:

• Previously generated checklists
• Project-specific quality patterns
• Common quality issues in this codebase

After completing:

• New checklist pattern → .claude/context/memory/learnings.md
• Quality issue found → .claude/context/memory/issues.md
• Context detection improvement → .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.