audit-deployment

Deploy Audit Skill

Analyze commits and technical changes since the last deployment or a specific date. Provide high-fidelity deployment diff summaries with risk assessment.

Formatting Rule: Always use emojis as defined in the report templates (headers, badges, status indicators). Emojis are part of the designed output format and should be preserved in all report formats (full, summary, html). Only omit emojis if the user explicitly requests a plain/no-emoji output.

Arguments

When invoked, extract these from the user's request:

• environment: prod, qa, staging (default: prod)
• --since=DATE: Compare current main against a specific date (YYYY-MM-DD)
• --format=FORMAT: Controls what content is generated — full (default), summary, or html
• --output=DESTINATION: Controls where the report goes — console (default) or file

Valid Combinations

--format	--output	Result
full (default)	console (default)	Full markdown report in terminal
summary	console	Condensed markdown in terminal
full	file	Full report saved to deployment-audit-{env}-{date}.md
summary	file	Summary saved to deployment-audit-{env}-{date}.md
html	(ignored)	Interactive dashboard saved to deployment-audit-{env}-{date}.html

When the user requests a "brief", "summary", "quick", or "executive" report, treat it as --format=summary.

Workflow

1. Context Discovery

• Extract environment (default: "prod")
• If --since is provided: Find base commit via git rev-list -n 1 --before="DATE" origin/main
• If no date: Try multiple deployment tracking methods:
  • OTK: Parse origin/otk-deploy:deploy/{environment}/*/values.yaml for version hash
    • Command: git show origin/otk-deploy:deploy/{environment}/pathway-navigator/values.yaml | grep "^ version:" | awk '{print $2}'
    • This returns format: YYYY.M.D-HASH (e.g., 2026.1.6-dddbdfb)
    • Extract hash: cut -d'-' -f2 to get the commit hash (e.g., dddbdfb)
    • Verify commit exists: git rev-parse --verify {hash}
    • Use this commit as the base reference for the diff
  • Docker: Check for deployment tags or release branches
  • Helm: Look for chart version references
  • Generic: Use last tag matching pattern v* or release-*

2. Project Type Detection

Auto-detect project type based on files present:

• .NET: *.csproj, *.sln, Controllers/, Startup.cs
• Node.js: package.json, routes/, app.js, server.js
• Python: requirements.txt, pyproject.toml, app.py, main.py
• Go: go.mod, main.go, handlers/
• Java: pom.xml, build.gradle, src/main/java
• Ruby: Gemfile, config/routes.rb
• Kotlin/Micronaut: build.gradle.kts, *.kt, src/main/kotlin, application.yml, micronaut-cli.yml
• React/Frontend: package.json + src/App.jsx or src/App.tsx, public/index.html, tsconfig.json
• Lambda: deploy.yaml (OTK lambda type), handler file (handler.ts, handler.py, handler.kt)

3. Commit Analysis

• Fetch all commits between base and origin/main
• Enrichment: Search commit messages for ticket patterns (Jira: IPS-123, Linear: ENG-456, GitHub: #123)
• Group commits by "Impact Areas" (API, Database, Config, Testing, Dependencies)

4. API Change Detection (Project-Aware)

Detect API frameworks and patterns:

• .NET: Controllers/, [HttpGet], [Route], *Controller.cs
• Node.js: routes/, app.get(), router., Express/Fastify patterns
• Python: @app.route, @router., FastAPI/Flask decorators
• Go: http.HandleFunc, router., Gin/Echo patterns
• Java: @RestController, @RequestMapping, Spring annotations
• Kotlin/Micronaut: @Controller, @Get, @Post, @Put, @Delete, @QueryValue, @PathVariable, @Body, *Controller.kt
• React/Frontend: Route definitions — <Route path="...">, createBrowserRouter, createRoutesFromElements, path changes in route config files

Breaking Change Audit (scan file diffs):

• Deleted API methods/endpoints
• Changed request/response schemas (DTOs, models)
• Route path modifications
• HTTP method changes
• Parameter additions/removals (required vs optional)
• Status code changes

Map every breaking change to its specific commit hash.

5. Schema & Database Change Detection

• Migration files: migrations/, *.sql, alembic/, knex/, flyway/
• Schema definitions: schema.sql, models/, entities/, *.graphql
• ORM changes: Entity Framework, Sequelize, SQLAlchemy, GORM model changes
• Micronaut Data: Entity changes, @MappedEntity, @Repository interfaces

6. Risk & Dependency Assessment

Dependency files (check for version bumps):

• Node.js: package.json, package-lock.json, yarn.lock
• .NET: *.csproj, packages.lock.json
• Python: requirements.txt, pyproject.toml, Pipfile
• Go: go.mod, go.sum
• Java: pom.xml, build.gradle
• Ruby: Gemfile, Gemfile.lock
• Kotlin: build.gradle.kts, gradle.properties, libs.versions.toml (Gradle version catalogs)

Environment variables (scan for new/changed config):

• .NET: appsettings.json, Configuration.GetSection
• Node.js: process.env, .env files
• Python: os.environ, settings.py
• Go: os.Getenv, config structs
• Docker: ENV instructions in Dockerfiles
• Kotlin/Micronaut: application.yml, application-{env}.yml, @Value, @ConfigurationProperties
• React/Frontend: .env, .env.local, .env.production, REACT_APP_* / VITE_* prefixed variables

Output Format

Template Selection

Choose the template based on --format:

• --format=full (default): Use references/TEMPLATE.md for comprehensive detailed analysis
• --format=summary: Use references/TEMPLATE_SUMMARY.md for executive summary
• --format=html: Use references/TEMPLATE_HTML.html via the HTML Fast Path below

The summary template provides a condensed view focusing on:

• Key metrics and risk level
• Critical changes only (features, breaking changes, dependencies)
• Quick deployment checklist
• Essential links

Output Destination

Controlled by --output:

• --output=console (default): Display the markdown report directly in the conversation
• --output=file: Save the report to a file
  • Filename format: deployment-audit-{environment}-{date}.md
  • Example: deployment-audit-prod-2026-01-14.md
  • Save to workspace root or user's Desktop if workspace root is not writable
  • After saving, inform the user of the file location

Note: When --format=html, the --output flag is ignored — HTML always writes a file.

HTML Fast Path (for --format=html)

Do NOT reproduce the CSS/JS template. Use targeted data injection instead:

1. Read references/TEMPLATE_HTML.html
2. Copy it to deployment-audit-{environment}-{date}.html (workspace root or Desktop)
3. Build only the AUDIT_DATA JavaScript object from the git analysis
4. Use the Edit tool to replace the block between %%AUDIT_DATA_START%% and %%AUDIT_DATA_END%% markers in the output file with the real data
5. Inform the user of the file location and suggest open deployment-audit-{env}-{date}.html

CRITICAL: Only produce the AUDIT_DATA object. Never reproduce the CSS, HTML structure, or JS renderer — they are already in the template.

AUDIT_DATA Schema Reference

The AUDIT_DATA object keys and types (see references/TEMPLATE_HTML.html sample for exact syntax):

Key	Type	Description
environment	"prod"|"staging"|"qa"	Target environment
projectType	string	Detected project type (e.g. ".NET 8.0")
projectName	string	Repo/project name
generatedAt	"YYYY-MM-DD"	Audit generation date
baseRef	{hash, date}	Base commit reference
targetRef	{hash, date}	Target (HEAD) commit reference
stats	{commitCount, filesChanged, additions, deletions}	Summary numbers
contributors	[{name, commits}]	Contributor list
tickets	string[]	Extracted ticket IDs
commits	[{hash, author, date, message, additions, deletions, area}]	Full commit list. area: "API"|"Database"|"Dependencies"|"Config"|"Testing"|"Docs"|"Other"
breakingChanges	[{type, component, change, commit, impact, description}]	Breaking changes. impact: "High"|"Medium"|"Low"
schemaChanges	[{category, change, files, impact}]	DB/schema changes
dependencyChanges	[{package, previous, new, type, notes}]	Dep updates. type: "Major"|"Minor"|"Patch"
infraChanges	[{component, change, impact}]	Infra/config changes
risk	{overall, factors: [{factor, level, detail}]}	Risk assessment. overall: "low"|"medium"|"high"|"critical"
rollback	{complexity, risk, estimatedTime, steps: [{step, action, cmd}]}	Rollback strategy
checklist	string[]	Pre-deployment checklist items
diffUrl	string	Optional GitHub compare URL

Use empty arrays [] for sections with no data. Do not include a files field on commit objects.

Breaking Change Indicators

Only flag changes that affect external API consumers (HTTP endpoints, request/response DTOs, public contracts). Always flag these as potential breaking changes:

• HTTP endpoint deletion or route path modifications
• Required parameter additions on request DTOs
• Response structure changes (removed/renamed fields, type changes)
• HTTP method or status code modifications
• Authentication/authorization changes

Do NOT flag as breaking changes:

• Internal interface or class signature changes (any file that is not a controller, route handler, or public API contract)
• New method overloads or parameter additions on internal services
• Changes to dependency injection, service registration, or internal wiring
• Refactoring of internal abstractions that don't alter HTTP behavior

Internal changes should be noted in the commit log and may contribute to risk assessment, but they are not breaking changes since they don't affect external API consumers.

Risk Level Guidelines

• Low: Documentation, tests, minor refactoring, additive changes only
• Medium: New features, non-breaking API additions, dependency updates
• High: Breaking API changes, schema migrations, config changes
• Critical: Multiple breaking changes combined with database migrations