Nm Pensive Api Review

Evaluate API surface design, consistency, documentation, and exemplar alignment

Security Scan

This instruction-only API-review skill is internally consistent with its stated purpose: it asks an agent to run local repository analysis commands and produce a structured audit, and it does not request unrelated credentials or install code.

Purpose & Capability

The skill's name/description (API review, consistency, docs) matches the instructions and included modules, which enumerate ripgrep/git/cargo/sphinx/tsc/etc commands used to catalog and audit a codebase. The declared required config paths (night-market.pensive:shared and night-market.imbue:proof-of-work) are consistent with the skill's need to capture reproducible command output and structured formatting.

Instruction Scope

Instructions direct the agent to scan the repository (rg across src, check docs, run git status, generate docs, etc.) and to record executed commands in an evidence log. This is appropriate for an API audit, but it means the skill will read potentially all files in the working tree and capture command output. The SKILL.md does not instruct sending data to external endpoints beyond referencing internal 'imbue' modules.

Install Mechanism

There is no install spec or code to write to disk: the skill is instruction-only. Low-risk in terms of installation; it relies on host binaries being present (rg, git, cargo, sphinx, go, tsc, npx, yq, etc.) but does not provision or download additional software.

Credentials

The skill requests no environment variables or external credentials, which is proportional. It does declare two required config paths (night-market.pensive:shared and night-market.imbue:proof-of-work). These appear to be internal Night Market/imbue configuration hooks used for command capture and structured output; users should verify that those config entries do not expose unrelated secrets or grant broader access than intended.

Persistence & Privilege

The skill is not marked always:true and does not request persistent system-wide privileges. Autonomous invocation is allowed (platform default) but there is no indication the skill attempts to modify other skills or global agent configuration.

Assessment

This skill is coherent for performing a repository-based API review: it will run local scanning commands and produce a structured evidence log. Before installing or invoking it, (1) confirm the two required config paths (night-market.pensive:shared and night-market.imbue:proof-of-work) are trustworthy and do not contain or grant access to secrets you don't want exposed; (2) avoid running this on repositories that contain sensitive secrets or credentials because the tool will read source/docs and record command output; (3) run it in a sandboxed environment or a checkout that strips secrets if you have concerns; and (4) ensure the host has the expected CLI tools available (rg, git, cargo, sphinx, tsc, etc.). Autonomous invocation is the platform default and not elevated here, but if you plan to allow the agent to run skills without supervision, review the evidence-capture settings so command outputs aren't exfiltrated outside your environment.

Night Market Skill — ported from claude-night-market/pensive. For the full experience with agents, hooks, and commands, install the Claude Code plugin.

API Review Workflow

Table of Contents

1. Usage
2. Required Progress Tracking
3. Workflow

Usage

Use this skill to review public API changes, design new surfaces, audit consistency, and validate documentation completeness. Run it before any API release to confirm alignment with project guidelines.

Required Progress Tracking

1. api-review:surface-inventory
2. api-review:exemplar-research
3. api-review:consistency-audit
4. api-review:docs-governance
5. api-review:evidence-log

Workflow

Step 1: Surface Inventory

Catalog all public APIs by language. Record stability levels, feature flags, and versioning metadata. Use tools like rg to find public symbols (e.g., pub in Rust or non-underscored def in Python). Confirm the working tree state with git status before starting.

Step 2: Exemplar Research

Identify at least two high-quality API references for the relevant language, such as pandas, requests, or tokio. Document their patterns for namespacing, pagination, error handling, and structure to serve as a baseline for the audit.

Step 3: Consistency Audit

Compare the project's API against the identified exemplar patterns. Analyze naming conventions, parameter ordering, return types, and error semantics. Identify duplication, leaky abstractions, missing feature gates, and documentation gaps.

Step 4: Documentation Governance

Validate that documentation includes entry points, quickstarts, and a complete API reference. Verify that changelogs and migration notes are maintained. Check for SemVer compliance, stability promises, and clear deprecation timelines. Confirm that documentation is generated automatically using tools like rustdoc, Sphinx, or OpenAPI.

Step 5: Evidence Log

Record all executed commands and findings. Summarize the final recommendation as Approve, Approve with actions, or Block. Include specific action items with assigned owners and due dates.

API Quality Checklist

Naming

Confirm consistent conventions and descriptive names that follow language-specific idioms.

Parameters

Verify consistent ordering and ensure optional parameters have explicit defaults. Check that type annotations are complete.

Return Values

Analyze return patterns for consistency. Confirm that error cases are documented and that pagination follows a uniform structure.

Documentation

Verify that all public APIs include usage examples and that the changelog reflects current changes.

Output Format

The final report must include a summary of the API surface, a numerical inventory of endpoints and public types, and an alignment analysis against researched exemplars. Document consistency issues and documentation gaps with precise file and line references. Conclude with a clear decision and a timed action plan.

Technical Integration

Use imbue:proof-of-work for reproducible command capture and imbue:structured-output for formatting findings. Reference imbue:diff-analysis/modules/risk-assessment-framework when assessing breaking changes.

Module Reference

• See modules/surface-inventory.md for API cataloging patterns
• See modules/exemplar-research.md for researching API standards
• See modules/consistency-audit.md for cross-API consistency checks

Troubleshooting

If the audit command is missing, verify that dependencies are installed and accessible in the system PATH. Check file permissions if access errors occur. Use the --verbose flag to inspect execution logs if the tool behaves unexpectedly.