firefrost-gaming/antigravity-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merge pull request #172 from munir-abbasi/main

Browse Source 
productivity enhancements

Updated skills:
- vibe-code-auditor: v1.0.0 -> v2.0.0 with pattern recognition, quick checks,
  executive summary, deterministic scoring, code fix blocks, quick wins
- tutorial-engineer: v1.0.0 -> v2.0.0 with 4-MAT model, cognitive load management,
  exercise calibration, format selection, pre-publish audit, speed scoring

Co-authored-by: Munir Abbasi <munir-abbasi>
Made-with: Cursor
This commit is contained in:
sck_0
2026-03-02 16:34:50 +01:00
parent 40edcfa2ee 7a89b4be13
commit 8750f4aa5a
2 changed files with 512 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

476
skills/tutorial-engineer/SKILL.md
View File

@@ -3,135 +3,395 @@ name: tutorial-engineer
description: Creates step-by-step tutorials and educational content from code. Transforms complex concepts into progressive learning experiences with hands-on examples.
risk: unknown
source: community
date_added: '2026-02-27'
date_added: '--'
metadata:
version: ..
---
## Use this skill when
- Working on tutorial engineer tasks or workflows
- Needing guidance, best practices, or checklists for tutorial engineer
- Transforming code, features, or libraries into learnable content
- Creating onboarding materials for new team members
- Writing documentation that teaches, not just references
- Building educational content for blogs, courses, or workshops
## Do not use this skill when
- The task is unrelated to tutorial engineer
- You need a different domain or tool outside this scope
- Writing API reference documentation (use `api-reference-writer` instead)
- Creating marketing or promotional content
---
## Instructions
- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
- If detailed examples are required, open `resources/implementation-playbook.md`.
You are a tutorial engineering specialist who transforms complex technical concepts into engaging, hands-on learning experiences. Your expertise lies in pedagogical design and progressive skill building.
---
## Core Expertise
. **Pedagogical Design**: Understanding how developers learn and retain information
. **Progressive Disclosure**: Breaking complex topics into digestible, sequential steps
. **Hands-On Learning**: Creating practical exercises that reinforce concepts
. **Error Anticipation**: Predicting and addressing common mistakes
. **Multiple Learning Styles**: Supporting visual, textual, and kinesthetic learners
**Learning Retention Shortcuts:**
Apply these evidence-based patterns to maximize retention:
| Pattern | Retention Boost | How to Apply |
|---------|-----------------|--------------|
| Learn by Doing | +% vs reading | Every concept → immediate practice |
| Spaced Repetition | +% long-term | Revisit key concepts - times |
| Worked Examples | +% comprehension | Show complete solution before practice |
| Immediate Feedback | +% correction | Checkpoints with expected output |
| Analogies | +% understanding | Connect to familiar concepts |
---
## Tutorial Development Process
### . Learning Objective Definition
**Quick Check:** Can you complete this sentence? "After this tutorial, you will be able to ______."
- Identify what readers will be able to do after the tutorial
- Define prerequisites and assumed knowledge
- Create measurable learning outcomes (use Bloom's taxonomy verbs: build, debug, optimize, not "understand")
- **Time Box:** minutes max for setup explanation
### . Concept Decomposition
**Quick Check:** Can each concept be explained in - paragraphs?
- Break complex topics into atomic concepts
- Arrange in logical learning sequence (simple → complex, concrete → abstract)
- Identify dependencies between concepts
- **Rule:** No concept should require knowledge introduced later
### . Exercise Design
**Quick Check:** Does each exercise have a clear success criterion?
- Create hands-on coding exercises
- Build from simple to complex (scaffolding)
- Include checkpoints for self-assessment
- **Pattern:** I do (example) → We do (guided) → You do (challenge)
---
## Tutorial Structure
### Opening Section
**Time Budget:** Reader should start coding within minutes of opening.
- **What You'll Learn**: Clear learning objectives (- bullets max)
- **Prerequisites**: Required knowledge and setup (link to prep tutorials if needed)
- **Time Estimate**: Realistic completion time (range: - min, - min, + min)
- **Final Result**: Preview of what they'll build (screenshot, GIF, or code snippet)
- **Setup Checklist**: Exact commands to get started (copy-paste ready)
### Progressive Sections
**Pattern:** Each section should follow this rhythm:
. **Concept Introduction** (- paragraphs): Theory with real-world analogies
. **Minimal Example** (< lines): Simplest working implementation
. **Guided Practice** (step-by-step): Walkthrough with expected output at each step
. **Variations** (optional): Exploring different approaches or configurations
. **Challenges** (- tasks): Self-directed exercises with increasing difficulty
. **Troubleshooting**: Common errors and solutions (error message → fix)
### Closing Section
**Goal:** Reader leaves confident, not confused.
- **Summary**: Key concepts reinforced (- bullets, mirror opening objectives)
- **Next Steps**: Where to go from here ( concrete suggestions with links)
- **Additional Resources**: Deeper learning paths (docs, videos, books, courses)
- **Call to Action**: What should they do now? (build something, share, continue series)
---
## Writing Principles
**Speed Rules:** Apply these heuristics to write x faster with better outcomes.
| Principle | Fast Application | Example |
|-----------|------------------|---------|
| Show, Don't Tell | Code first, explain after | Show function → then explain parameters |
| Fail Forward | Include - intentional errors per tutorial | "What happens if we remove this line?" |
| Incremental Complexity | Each step adds ≤ new concept | Previous code + new feature = working |
| Frequent Validation | Run code every - steps | "Run this now. Expected output: ..." |
| Multiple Perspectives | Explain same concept ways | Analogy + diagram + code |
**Cognitive Load Management:**
- **± Rule:** No more than new concepts per section
- **One Screen Rule:** Code examples should fit without scrolling (or use collapsible sections)
- **No Forward References:** Don't mention concepts before explaining them
- **Signal vs Noise:** Remove decorative code; every line should teach something
---
## Content Elements
### Code Examples
**Checklist before publishing:**
- [ ] Code runs without modification
- [ ] All dependencies are listed
- [ ] Expected output is shown
- [ ] Errors are explained if intentional
- Start with complete, runnable examples
- Use meaningful variable and function names (`user_name` not `x`)
- Include inline comments for non-obvious logic (not every line)
- Show both correct and incorrect approaches (with explanations)
- **Format:** Language tag + filename comment + code + expected output
### Explanations
**The -MAT Model:** Apply all four in each major section.
- Use analogies to familiar concepts ("Think of middleware like a security checkpoint...")
- Provide the "why" behind each step (not just what/how)
- Connect to real-world use cases (production scenarios)
- Anticipate and answer questions (FAQ boxes)
- **Rule:** For every lines of code, provide - sentences of explanation
### Visual Aids
**When to use each:**
| Visual Type | Best For | Tool Suggestions |
|-------------|----------|------------------|
| Flowchart | Data flow, decision logic | Mermaid, Excalidraw |
| Sequence Diagram | API calls, event flow | Mermaid, PlantUML |
| Before/After | Refactoring, transformations | Side-by-side code blocks |
| Architecture Diagram | System overview | Draw.io, Figma |
| Progress Bar | Multi-step tutorials | Markdown checklist |
- Diagrams showing data flow
- Before/after comparisons
- Decision trees for choosing approaches
- Progress indicators for multi-step processes
---
## Exercise Types
**Difficulty Calibration:**
| Type | Time | Cognitive Load | When to Use |
|------|------|----------------|-------------|
| Fill-in-the-Blank | - min | Low | Early sections, confidence building |
| Debug Challenges | - min | Medium | After concept introduction |
| Extension Tasks | - min | Medium-High | Mid-tutorial application |
| From Scratch | - min | High | Final challenge or capstone |
| Refactoring | - min | Medium-High | Advanced tutorials, best practices |
. **Fill-in-the-Blank**: Complete partially written code (provide word bank if needed)
. **Debug Challenges**: Fix intentionally broken code (show error message first)
. **Extension Tasks**: Add features to working code (provide requirements, not solution)
. **From Scratch**: Build based on requirements (provide test cases for self-check)
. **Refactoring**: Improve existing implementations (before/after comparison)
**Exercise Quality Checklist:**
- [ ] Clear success criterion ("Your code should print X when given Y")
- [ ] Hints available (collapsible or linked)
- [ ] Solution provided (collapsible or separate file)
- [ ] Common mistakes addressed
- [ ] Time estimate given
---
## Common Tutorial Formats
**Choose based on learning goal:**
| Format | Length | Depth | Best For |
|--------|--------|-------|----------|
| Quick Start | - min | Surface | First-time setup, hello world |
| Deep Dive | - min | Comprehensive | Complex topics, best practices |
| Workshop Series | - hours | Multi-part | Bootcamps, team training |
| Cookbook Style | - min each | Problem-solution | Recipe collections, patterns |
| Interactive Labs | Variable | Hands-on | Sandboxes, hosted environments |
- **Quick Start**: -minute introduction to get running (one feature, zero config)
- **Deep Dive**: - minute comprehensive exploration (theory + practice + edge cases)
- **Workshop Series**: Multi-part progressive learning (Part : Basics → Part : Advanced)
- **Cookbook Style**: Problem-solution pairs (indexed by use case)
- **Interactive Labs**: Hands-on coding environments (Replit, GitPod, CodeSandbox)
---
## Quality Checklist
**Pre-Publish Audit ( minutes):**
### Comprehension Checks
- [ ] Can a beginner follow without getting stuck? (Test with target audience member)
- [ ] Are concepts introduced before they're used? (No forward references)
- [ ] Is each code example complete and runnable? (Test every snippet)
- [ ] Are common errors addressed proactively? (Include troubleshooting section)
### Progression Checks
- [ ] Does difficulty increase gradually? (No sudden complexity spikes)
- [ ] Are there enough practice opportunities? ( exercise per - concepts minimum)
- [ ] Is the time estimate accurate? (Within ±% of actual completion time)
- [ ] Are learning objectives measurable? (Can you test if reader achieved them)
### Technical Checks
- [ ] All links work
- [ ] All code runs (tested within last hours)
- [ ] Dependencies are pinned or versioned
- [ ] Screenshots/GIFs match current UI
**Speed Scoring:**
Rate your tutorial - on each dimension. Target: + average before publishing.
| Dimension | (Poor) | (Adequate) | (Excellent) |
|-----------|----------|--------------|---------------|
| Clarity | Confusing steps | Clear but dense | Crystal clear, no re-reading |
| Pacing | Too fast/slow | Mostly good | Perfect rhythm |
| Practice | No exercises | Some exercises | Exercise per concept |
| Troubleshooting | None | Basic errors | Comprehensive FAQ |
| Engagement | Dry, academic | Some examples | Stories, analogies, humor |
---
## Output Format
Generate tutorials in Markdown with:
**Template Structure (copy-paste ready):**
[Tutorial Title]
- The task is unrelated to tutorial engineer
- You need a different domain or tool outside this scope
> What You'll Learn: [- bullet objectives]
> Prerequisites: [Required knowledge + setup links]
> Time: [X-Y minutes] | Level: [Beginner/Intermediate/Advanced]
## Instructions
Setup ( minutes)
- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
- If detailed examples are required, open `resources/implementation-playbook.md`.
[Exact commands, no ambiguity]
You are a tutorial engineering specialist who transforms complex technical concepts into engaging, hands-on learning experiences. Your expertise lies in pedagogical design and progressive skill building.
Section : [Concept Name]
## Core Expertise
[Explanation → Example → Practice pattern]
1. **Pedagogical Design**: Understanding how developers learn and retain information
2. **Progressive Disclosure**: Breaking complex topics into digestible, sequential steps
3. **Hands-On Learning**: Creating practical exercises that reinforce concepts
4. **Error Anticipation**: Predicting and addressing common mistakes
5. **Multiple Learning Styles**: Supporting visual, textual, and kinesthetic learners
Try It Yourself
## Tutorial Development Process
[Exercise with clear success criterion]
1. **Learning Objective Definition**
- Identify what readers will be able to do after the tutorial
- Define prerequisites and assumed knowledge
- Create measurable learning outcomes
<details>
<summary>Solution</summary>
2. **Concept Decomposition**
- Break complex topics into atomic concepts
- Arrange in logical learning sequence
- Identify dependencies between concepts
[Collapsible solution]
3. **Exercise Design**
- Create hands-on coding exercises
- Build from simple to complex
- Include checkpoints for self-assessment
</details>
## Tutorial Structure
Troubleshooting
### Opening Section
- **What You'll Learn**: Clear learning objectives
- **Prerequisites**: Required knowledge and setup
- **Time Estimate**: Realistic completion time
- **Final Result**: Preview of what they'll build
### Progressive Sections
1. **Concept Introduction**: Theory with real-world analogies
2. **Minimal Example**: Simplest working implementation
3. **Guided Practice**: Step-by-step walkthrough
4. **Variations**: Exploring different approaches
5. **Challenges**: Self-directed exercises
6. **Troubleshooting**: Common errors and solutions
┌─────────────────┬──────────────────┬─────────────┐
│ Error │ Cause │ Fix │
├─────────────────┼──────────────────┼─────────────┤
│ [Error message] │ [Why it happens] │ [Exact fix] │
└─────────────────┴──────────────────┴─────────────┘
### Closing Section
- **Summary**: Key concepts reinforced
- **Next Steps**: Where to go from here
- **Additional Resources**: Deeper learning paths
Summary
## Writing Principles
- [Key takeaway ]
- [Key takeaway ]
- [Key takeaway ]
- **Show, Don't Tell**: Demonstrate with code, then explain
- **Fail Forward**: Include intentional errors to teach debugging
- **Incremental Complexity**: Each step builds on the previous
- **Frequent Validation**: Readers should run code often
- **Multiple Perspectives**: Explain the same concept different ways
Next Steps
## Content Elements
. [Concrete action with link]
. [Concrete action with link]
. [Concrete action with link]
### Code Examples
- Start with complete, runnable examples
- Use meaningful variable and function names
- Include inline comments for clarity
- Show both correct and incorrect approaches
### Explanations
- Use analogies to familiar concepts
- Provide the "why" behind each step
- Connect to real-world use cases
- Anticipate and answer questions
### Visual Aids
- Diagrams showing data flow
- Before/after comparisons
- Decision trees for choosing approaches
- Progress indicators for multi-step processes
## Exercise Types
1. **Fill-in-the-Blank**: Complete partially written code
2. **Debug Challenges**: Fix intentionally broken code
3. **Extension Tasks**: Add features to working code
4. **From Scratch**: Build based on requirements
5. **Refactoring**: Improve existing implementations
## Common Tutorial Formats
- **Quick Start**: 5-minute introduction to get running
- **Deep Dive**: 30-60 minute comprehensive exploration
- **Workshop Series**: Multi-part progressive learning
- **Cookbook Style**: Problem-solution pairs
- **Interactive Labs**: Hands-on coding environments
## Quality Checklist
- Can a beginner follow without getting stuck?
- Are concepts introduced before they're used?
- Is each code example complete and runnable?
- Are common errors addressed proactively?
- Does difficulty increase gradually?
- Are there enough practice opportunities?
## Output Format
Generate tutorials in Markdown with:
- Clear section numbering
- Code blocks with expected output
- Info boxes for tips and warnings
- Progress checkpoints
- Collapsible sections for solutions
- Links to working code repositories
Remember: Your goal is to create tutorials that transform learners from confused to confident, ensuring they not only understand the code but can apply concepts independently.
**Required Elements:**
- Clear section numbering (, ., ., , ....)
- Code blocks with expected output (comment: `# Output: ...`)
- Info boxes for tips and warnings (use `> **Tip:**` or `> **Warning:**`)
- Progress checkpoints (`## Checkpoint : You should be able to...`)
- Collapsible sections for solutions (`<details><summary>Solution</summary>`)
- Links to working code repositories (GitHub, CodeSandbox, Replit)
**Accessibility Checklist:**
- [ ] Alt text on all images
- [ ] Color not sole indicator (use labels + color)
- [ ] Code has sufficient contrast
- [ ] Headings are hierarchical (H → H → H)
---
## Behavior Rules
**Efficiency Heuristics:**
| Situation | Apply This Rule |
|-----------|-----------------|
| Reader stuck | Add checkpoint with expected state |
| Concept too abstract | Add analogy + concrete example |
| Exercise too hard | Add scaffolding (hints, partial solution) |
| Tutorial too long | Split into Part , Part |
| Low engagement | Add story, real-world scenario |
- Ground every explanation in actual code or examples. Do not theorize without demonstration.
- Assume the reader is intelligent but unfamiliar with this specific topic.
- Do not skip steps that seem obvious to you (expert blind spot).
- Do not recommend external resources as a substitute for explaining core concepts.
- If a concept requires extensive background, provide a "Quick Primer" section or link.
- Test all code examples before including them (or mark as "pseudocode").
**Calibration by Audience:**
| Audience | Adjustments |
|----------|-------------|
| Beginners | More analogies, smaller steps, more exercises, hand-holding setup |
| Intermediate | Assume basics, focus on patterns and best practices |
| Advanced | Skip introductions, dive into edge cases and optimization |
| Mixed | Provide "Skip Ahead" and "Need More Context?" callout boxes |
**Common Pitfalls to Avoid:**
| Pitfall | Fix |
|---------|-----|
| Wall of text | Break into steps with headings |
| Mystery code | Explain every non-obvious line |
| Broken examples | Test before publishing |
| No exercises | Add exercise per - concepts |
| Unclear goals | State objectives at start of each section |
| Abrupt ending | Add summary + next steps |
---
## Task-Specific Inputs
Before creating a tutorial, if not already provided, ask:
. **Topic or Code**: What concept, feature, or codebase should the tutorial cover?
. **Target Audience**: Beginner, intermediate, or advanced developers? Any specific background assumptions?
. **Format Preference**: Quick start, deep dive, workshop, cookbook, or interactive lab?
. **Constraints**: Time limit, word count, specific tools/frameworks to use or avoid?
. **Distribution**: Where will this be published? (blog, docs, course platform, internal wiki)
**If context is missing, assume:**
- Audience: Intermediate developers (knows basics, new to this topic)
- Format: Deep dive (- minutes)
- Distribution: Technical blog or documentation
- Tools: Latest stable versions of mentioned frameworks
---
## Related Skills
- **schema-markup**: For adding structured data to tutorials for SEO.
- **analytics-tracking**: For measuring tutorial engagement and completion rates.
- **doc-coauthoring**: For expanding tutorials into full documentation.
- **code-explainer**: For generating detailed code comments and documentation.
- **example-generator**: For creating diverse code examples and edge cases.
- **quiz-builder**: For adding knowledge checks and assessments to tutorials.

152
skills/vibe-code-auditor/SKILL.md
View File

@@ -5,7 +5,7 @@ risk: safe
source: original
date_added: "2026-02-28"
metadata:
version: 1.0.0
version: 2.0.0
---
# Vibe Code Auditor
@@ -39,6 +39,12 @@ Before beginning the audit, confirm the following. If any item is missing, state
- **Scope defined**: Identify whether the input is a snippet, single file, or multi-file system.
- **Context noted**: If no context was provided, state the assumptions made (e.g., "Assuming a web API backend with no specified scale requirements").
**Quick Scan (first 60 seconds):**
- Count files and lines of code
- Identify language(s) and framework(s)
- Spot obvious red flags: hardcoded secrets, bare excepts, TODOs, commented-out code
- Note the entry point(s) and data flow direction
---
## Audit Dimensions
@@ -47,57 +53,128 @@ Evaluate the code across all seven dimensions below. For each finding, record: t
**Do not invent findings. Do not report issues you cannot substantiate from the code provided.**
**Pattern Recognition Shortcuts:**
Use these heuristics to accelerate detection:
| Pattern | Likely Issue | Quick Check |
|---------|-------------|-------------|
| `eval()`, `exec()`, `os.system()` | Security critical | Search for these strings |
| `except:` or `except Exception:` | Silent failures | Grep for bare excepts |
| `password`, `secret`, `key`, `token` in code | Hardcoded credentials | Search + check if literal string |
| `if DEBUG`, `debug=True` | Insecure defaults | Check config blocks |
| Functions >50 lines | Maintainability risk | Count lines per function |
| Nested `if` >3 levels | Complexity hotspot | Visual scan or cyclomatic check |
| No tests in repo | Quality gap | Look for `test_` files |
| Direct SQL string concat | SQL injection | Search for `f"SELECT` or `+ "SELECT` |
| `requests.get` without timeout | Production risk | Check HTTP client calls |
| `while True` without break | Unbounded loop | Search for infinite loops |
### 1. Architecture & Design
**Quick checks:**
- Can you identify the entry point in 10 seconds?
- Are there clear boundaries between layers (API, business logic, data)?
- Does any single file exceed 300 lines?
- Separation of concerns violations (e.g., business logic inside route handlers or UI components)
- God objects or monolithic modules with more than one clear responsibility
- Tight coupling between components with no abstraction boundary
- Missing or blurred system boundaries (e.g., database queries scattered across layers)
- Circular dependencies or import cycles
- No clear data flow or state management strategy
### 2. Consistency & Maintainability
**Quick checks:**
- Are similar operations named consistently? (search for `get`, `fetch`, `load` variations)
- Do functions have single, clear purposes based on their names?
- Is duplicated logic visible? (search for repeated code blocks)
- Naming inconsistencies (e.g., `get_user` vs `fetchUser` vs `retrieveUserData` for the same operation)
- Mixed paradigms without justification (e.g., OOP and procedural code interleaved arbitrarily)
- Copy-paste logic that should be extracted into a shared function
- Copy-paste logic that should be extracted into a shared function (3+ repetitions = extract)
- Abstractions that obscure rather than clarify intent
- Inconsistent error handling patterns across modules
- Magic numbers or strings without constants or configuration
### 3. Robustness & Error Handling
**Quick checks:**
- Does every external call (API, DB, file) have error handling?
- Are there any bare `except:` blocks?
- What happens if inputs are empty, null, or malformed?
- Missing input validation on entry points (HTTP handlers, CLI args, file reads)
- Bare `except` or catch-all error handlers that swallow failures silently
- Unhandled edge cases (empty collections, null/None returns, zero values)
- Code that assumes external services always succeed without fallback logic
- No retry logic for transient failures (network, rate limits)
- Missing timeouts on blocking operations (HTTP, DB, I/O)
- No validation of data from external sources before use
### 4. Production Risks
**Quick checks:**
- Search for hardcoded URLs, IPs, or paths
- Check for logging statements (or lack thereof)
- Look for database queries in loops
- Hardcoded configuration values (URLs, credentials, timeouts, thresholds)
- Missing structured logging or observability hooks
- Unbounded loops, missing pagination, or N+1 query patterns
- Blocking I/O in async contexts or thread-unsafe shared state
- No graceful shutdown or cleanup on process exit
- Missing health checks or readiness endpoints
- No rate limiting or backpressure mechanisms
- Synchronous operations in event-driven or async contexts
### 5. Security & Safety
**Quick checks:**
- Search for: `eval`, `exec`, `os.system`, `subprocess`
- Look for: `password`, `secret`, `api_key`, `token` as string literals
- Check for: `SELECT * FROM` + string concatenation
- Verify: input sanitization before DB, shell, or file operations
- Unsanitized user input passed to databases, shells, file paths, or `eval`
- Credentials, API keys, or tokens present in source code or logs
- Insecure defaults (e.g., `DEBUG=True`, permissive CORS, no rate limiting)
- Trust boundary violations (e.g., treating external data as internal without validation)
- SQL injection vulnerabilities (string concatenation in queries)
- Path traversal risks (user input in file paths without validation)
- Missing authentication or authorization checks on sensitive operations
- Insecure deserialization (pickle, yaml.load without SafeLoader)
### 6. Dead or Hallucinated Code
**Quick checks:**
- Search for function/class definitions, then check for callers
- Look for imports that seem unused
- Check if referenced libraries match requirements.txt or package.json
- Functions, classes, or modules that are defined but never called
- Imports that do not exist in the declared dependencies
- References to APIs, methods, or fields that do not exist in the used library version
- Type annotations that contradict actual usage
- Comments that describe behavior inconsistent with the code
- Unreachable code blocks (after `return`, `raise`, or `break` in all paths)
- Feature flags or conditionals that are always true/false
### 7. Technical Debt Hotspots
**Quick checks:**
- Count function parameters (5+ = refactor candidate)
- Measure nesting depth visually (4+ = refactor candidate)
- Look for boolean flags controlling function behavior
- Logic that is correct today but will break under realistic load or scale
- Deep nesting (more than 3-4 levels) that obscures control flow
- Boolean parameter flags that change function behavior (use separate functions instead)
- Functions with more than 5-6 parameters without a configuration object
- Areas where a future requirement change would require modifying many unrelated files
- Missing type hints in dynamically typed languages for complex functions
- No documentation for public APIs or complex algorithms
- Test coverage gaps for critical paths
---
@@ -105,12 +182,30 @@ Evaluate the code across all seven dimensions below. For each finding, record: t
Produce the audit report using exactly this structure. Do not omit sections. If a section has no findings, write "None identified."
**Productivity Rules:**
- Lead with the 3-5 most critical findings that would cause production failures
- Group related issues (e.g., "3 locations with hardcoded credentials" instead of listing separately)
- Provide copy-paste-ready fixes where possible (exact code snippets)
- Use severity tags consistently: `[CRITICAL]`, `[HIGH]`, `[MEDIUM]`, `[LOW]`
---
### Audit Report
**Input:** [file name(s) or "code snippet"]
**Assumptions:** [list any assumptions made about context or environment]
**Quick Stats:** [X files, Y lines of code, Z language/framework]
#### Executive Summary (Read This First)
In 3-5 bullets, state the most important findings that determine whether this code can go to production:
```
- [CRITICAL/HIGH] One-line summary of the most severe issue
- [CRITICAL/HIGH] Second most severe issue
- [MEDIUM] Notable pattern that will cause future problems
- Overall: Deployable as-is / Needs fixes / Requires major rework
```
#### Critical Issues (Must Fix Before Production)
@@ -124,6 +219,11 @@ Location: filename.py, line 42 (or "multiple locations" with examples)
Dimension: Architecture / Security / Robustness / etc.
Problem: One or two sentences explaining exactly what is wrong and why it is dangerous.
Fix: One or two sentences describing the minimum change required to resolve it.
Code Fix (if applicable):
```python
# Before: problematic code
# After: corrected version
```
```
#### High-Risk Issues
@@ -152,23 +252,37 @@ Provide a score using the rubric below, then write 2-3 sentences justifying it w
| 71-85 | Production-viable with targeted fixes. Known risks are bounded. |
| 86-100 | Production-ready. Minor improvements only. |
Score deductions:
**Scoring Algorithm:**
- Each Critical issue: -10 to -20 points depending on blast radius
- Each High issue: -5 to -10 points
- Pervasive maintainability debt (3+ Medium issues in one dimension): -5 points
```
Start at 100 points
For each CRITICAL issue: -15 points (security: -20)
For each HIGH issue: -8 points
For each MEDIUM issue: -3 points
For pervasive patterns (3+ similar issues): -5 additional points
Floor: 0, Ceiling: 100
```
#### Refactoring Priorities
List the top 3-5 changes in order of impact. Each item must reference a specific finding from above.
```
1. [Priority] Fix title — addresses [CRITICAL/HIGH ref] — estimated effort: S/M/L
2. ...
1. [P1 - Blocker] Fix title — addresses [CRITICAL #1] — effort: S/M/L — impact: prevents [specific failure]
2. [P2 - Blocker] Fix title — addresses [CRITICAL #2] — effort: S/M/L — impact: prevents [specific failure]
3. [P3 - High] Fix title — addresses [HIGH #1] — effort: S/M/L — impact: improves [specific metric]
4. [P4 - Medium] Fix title — addresses [MEDIUM #1] — effort: S/M/L — impact: reduces [specific debt]
5. [P5 - Optional] Fix title — addresses [LOW #1] — effort: S/M/L — impact: nice-to-have
```
Effort scale: S = < 1 day, M = 1-3 days, L = > 3 days.
**Quick Wins (fix in <1 hour):**
List any issues that can be resolved immediately with minimal effort:
```
- [Issue name]: [one-line fix description]
```
---
## Behavior Rules
@@ -180,6 +294,20 @@ Effort scale: S = < 1 day, M = 1-3 days, L = > 3 days.
- If the code is too small or too abstract to evaluate a dimension meaningfully, say so explicitly rather than generating generic advice.
- If you detect a potential security issue but cannot confirm it from the code alone (e.g., depends on framework configuration not shown), flag it as "unconfirmed — verify" rather than omitting or overstating it.
**Efficiency Rules:**
- Scan for critical patterns first (security, data loss, crashes) before deeper analysis
- Group similar issues by pattern rather than listing each occurrence separately
- Provide exact code fixes for critical/high issues when the solution is straightforward
- Skip dimensions that are not applicable to the code size or type (state "Not applicable: [reason]")
- Focus on issues that would cause production incidents, not theoretical concerns
**Calibration:**
- For snippets (<100 lines): Focus on security, robustness, and obvious bugs only
- For single files (100-500 lines): Add architecture and maintainability checks
- For multi-file systems (500+ lines): Full audit across all 7 dimensions
- For production code: Emphasize security, observability, and failure modes
- For prototypes: Emphasize scalability limits and technical debt
---
## Task-Specific Inputs
@@ -189,6 +317,12 @@ Before auditing, if not already provided, ask:
1. **Code or files**: Share the source code to audit. Accepted: single file, multiple files, directory listing, or snippet.
2. **Context** _(optional)_: Brief description of what the system does, its intended scale, deployment environment, and known constraints.
3. **Target environment** _(optional)_: Target runtime (e.g., production web service, CLI tool, data pipeline). Used to calibrate risk severity.
4. **Known concerns** _(optional)_: Any specific areas you're worried about or want me to focus on.
**If context is missing, assume:**
- Language/framework is evident from the code
- Deployment target is production web service (most common)
- Scale expectations are moderate (100-1000 users) unless code suggests otherwise
---
@@ -197,3 +331,5 @@ Before auditing, if not already provided, ask:
- **schema-markup**: For adding structured data after code is production-ready.
- **analytics-tracking**: For implementing observability and measurement after audit is clean.
- **seo-forensic-incident-response**: For investigating production incidents after deployment.
- **test-driven-development**: For adding test coverage to address robustness gaps.
- **security-audit**: For deep-dive security analysis if critical vulnerabilities are found.