Nestjs Feature Audit

NestJS Feature Audit

Compare one feature's documented target with the implementation at one identified revision. Return a traceable status report; do not fix findings.

Pre-execution conflict guard

Run this guard after identifying every applicable skill and before editing files, switching branches, fetching or fast-forwarding Git refs, installing packages, generating code, running migrations, or executing any other state-changing command. Read-only repository inspection is allowed while resolving the guard.

Prerequisites

• Require a non-empty feature name and resolve the target branch, defaulting to main only when the user did not name one.
• Read repository instructions and inspect the current branch, worktree state, remotes, target branch, and available documentation before changing Git state.
• Treat the roadmap as the expected-state authority. Treat code, tests, generated contracts, configuration, and safe runtime evidence as current-state evidence.
• Do not infer requirements solely from issue titles, filenames, comments, or remembered conversation.

Primary ownership

This skill owns target-branch preparation, feature/roadmap discovery, roadmap-to-code traceability, status classification, and the four-section feature report.

• nestjs-code-audit owns whole-repository quality-gate collection, finding severity, and cross-domain code-quality reports. This skill may use its verified findings but keeps roadmap coverage as the organizing contract.
• nestjs-architecture-principles, nestjs-oop-design-patterns, and nestjs-features-performance own architecture, object-design, and runtime/security/testing judgments respectively.
• nestjs-professional-software-engineering owns separately authorized fixes. A feature-audit request alone is not implementation authorization.
• nestjs-git-commit-pr-message owns publication of an explicitly requested report or later verified fixes. It does not make an incomplete feature complete.

Conflict test

A conflict exists when active skills would:

• inspect different branches, revisions, feature boundaries, or roadmaps;
• mutate the worktree while this audit is collecting a stable baseline;
• classify the same roadmap item incompatibly without one evidence-backed owner;
• treat roadmap text as permission to execute migrations, deployments, load tests, or other live actions; or
• proceed without the roadmap, repository state, dependency, environment, or authorization needed for a reliable claim.

Resolve conflicts using explicit user intent, repository contracts and the named roadmap, verified source/runtime constraints, then the narrowest owner above. If the baseline or ownership remains ambiguous, stop before mutation and state the smallest missing decision. Never blend evidence from different revisions or convert the audit into an implementation.

Invocation

Preferred portable invocation:

$nestjs-feature-audit "payments"
$nestjs-feature-audit "payments" --branch "release/2026-q3"

If a host already routes the user's requested command syntax, parse it equivalently:

/audit_feature payments
/audit_feature payments on branch release/2026-q3

Do not claim that bare /audit_feature is installed on every client. On Codex, the optional compatibility prompt is /prompts:audit_feature; installed skills remain the preferred interface.

Required workflow

1. Prepare the target branch safely

1. Resolve the repository root and read its instructions before any Git mutation.
2. Record git status --short --branch, the current branch, remotes, and the local/remote existence of the target branch.
3. If the worktree is dirty, a Git operation is in progress, or the checkout is detached, stop before switching or updating. Never stash, discard, reset, clean, or force-switch automatically. Continue on the same dirty snapshot only when the user explicitly accepts it, and record that exception in the report.
4. When a remote-tracking branch exists, fetch its remote, switch normally, and fast-forward only. Never merge divergent history or rebase as part of an audit.
5. Record the audited branch, commit SHA, dirty state, remote revision, and whether freshness was verified. If a configured remote cannot be checked, stop before claiming the branch is current unless the user explicitly accepts the local snapshot.

Use equivalent safe commands for the repository:

git status --short --branch
git branch --show-current
git remote -v
git fetch --prune origin
git switch -- "$audit_branch"
git merge --ff-only -- "origin/$audit_branch"
git rev-parse HEAD

The explicit feature-audit invocation authorizes safe target-branch selection and fast-forward preparation. It does not authorize destructive cleanup or publication.

2. Gather context and enforce the roadmap gate

1. Read project principles, concepts, standards, architectural decisions, and contributor rules that apply to the feature.
2. Search docs/ filenames and contents for the feature name, accepted aliases, roadmap, plan, milestone, phase, acceptance, and migration.
3. Identify feature code through entry points, modules, providers, adapters, persistence, configuration, migrations, tests, contracts, telemetry, and deployment artifacts. Search first; do not trust folder names alone.
4. Use requirements and decisions from available conversation context only as secondary evidence. If conversation history is unavailable, say so; do not fabricate it or block when the repository roadmap is sufficient.
5. Accept a roadmap only when it defines an identifiable feature scope and concrete target items, phases, acceptance conditions, or migration outcomes. A title, TODO mention, changelog entry, or generic product description is not a clear roadmap.

If no clear roadmap exists in docs/, stop before implementation comparison and ask the user to provide or identify it. Report the paths and terms searched. A roadmap supplied directly by the user satisfies the gate; label it as user-provided rather than repository documentation. Follow roadmap-discovery.md for the complete gate.

3. Build the traceability matrix

For every roadmap item:

1. Normalize the requirement without weakening its acceptance language.
2. Trace it to source, tests, configuration, schema/migrations, generated contracts, deployment/runtime evidence, and relevant standards.
3. Record verified, partial, absent, superseded, broken, blocked, or not verifiable as the observed state.
4. Assign exactly one primary report category. Split a roadmap item into explicit sub-items when its parts have different states.
5. Keep a path-and-line citation or exact command/result for every positive and negative claim. Absence claims must include the searches and expected integration points checked.

Use evidence-classification.md to distinguish completed work, gaps, legacy implementations, defects, blockers, and unverified candidates.

4. Cross-reference domain standards

• Compare architecture claims with actual module/import, dependency, data/write, transaction, and service boundaries.
• Compare object-design claims with real responsibilities, invariants, collaborators, and variation.
• Compare runtime claims with lifecycle wiring, security controls, tests, configuration, built artifacts, and authorized runtime evidence.
• Mark tests, deployments, migrations, external systems, or runtime checks as not verified when they were unavailable or unsafe. Do not convert not run into success or failure.
• Distinguish roadmap completion from production proof: merged source may be implemented while a rollout or live acceptance item remains blocked.

5. Return the required report

Start with the feature, branch, commit, dirty/freshness state, roadmap source, audited scope, and a one-sentence verdict. Then include these headings exactly and in this order:

1. ✅ Implemented
2. ❌ Missing/Not Implemented
3. ⚠️ Legacy Code
4. 🛑 Bugs & Blockers

Each item must name the roadmap requirement, observed state, evidence, impact, and next validation or exit evidence. Keep all four headings; write None found in the audited evidence. when a category is empty. Use report-template.md.

Do not assign a completion percentage unless the roadmap defines item weights. Do not implement, commit, push, deploy, or edit the roadmap unless the user separately requests that action.

Reference routing