playbooks

home / skills / vishalsachdev / claude-skills / codebase-singularity

codebase-singularity skill

/codebase-singularity

This skill applies the codebase singularity approach to perform safe, minimal-diff repo changes with explicit validation and exit criteria.

npx playbooks add skill vishalsachdev/claude-skills --skill codebase-singularity

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
2.6 KB
---
name: codebase-singularity
description: "Apply the codebase singularity approach: reliable codebase understanding and change with a repeatable workflow, guardrails, and verification gates. Use for repo work (feature, bugfix, refactor, migration) when you need high trust, minimal diffs, and explicit validation and exit criteria."
---

# Codebase Singularity

## Quick start
1. Collect inputs: repo path, goal, constraints, risk tolerance, and validation commands.
2. Prime: list files, read README, and inspect entry points.
3. Summarize: explain repo shape and where the change belongs; ask questions if ambiguous.
4. Plan: write a short plan with success criteria and validation steps.
5. Change: implement the smallest viable patch; avoid unrelated refactors.
6. Validate: run the requested command(s) or the closest available; record results.
7. Wrap up: report changes, evidence, risks, and next steps.

## Inputs
- Repo path and task goal.
- Constraints (files to avoid, time or risk limits, API stability).
- Validation commands (tests, lint, build, or targeted checks).

## Outputs
- Short plan with success criteria.
- Minimal patch.
- Evidence: commands run and results.
- Wrap-up: what changed, why, risks, and next steps.

## Grades (maturity ladder)

### Grade 1: Prime only
- Prime, summarize, and stop on ambiguity.

### Grade 2: Specialized roles + verification
- Add role prompts (e.g., test_writer, docs_fetcher, reviewer).
- Require a verification step for each role.

### Grade 3: Tooling expansion
- Declare required tools or services and expected outputs.
- Prefer tools over guessing (e.g., query schema instead of inferring).

### Grade 4: Closed-loop autonomy
- Run cycles: request -> validate -> resolve.
- Add hard exits: max iterations, evidence of progress, stop after repeated failures.

## Guardrails
- Keep diffs small.
- Always validate; if you cannot, say so and propose a safe next step.
- Ask before broad refactors or scope expansion.

## Templates

### Safe bugfix
```
Goal: Fix <bug> with minimal change.
Constraints: Do not modify public API; avoid touching <paths>.
Validation: Run `...` and paste output.
Exit conditions: Stop after 2 failed attempts; summarize hypotheses and logs.
Deliverables: Patch + explanation + risks.
```

### Add a feature
```
Goal: Add <feature>.
Constraints: Keep scope to <module>; no new dependencies.
Validation: Run `...`.
Deliverables: Patch + tests + short doc update.
```

## References
- Read `references/video.md` for a concise source summary.
- Read `references/transcript.md` for full context.
- Read `references/visual-notes.md` for a visual outline.

Overview

This skill applies the codebase singularity approach to deliver reliable, minimal, and verifiable changes to a repository. It guides a repeatable workflow with guardrails, explicit validation gates, and clear exit criteria to increase trust in feature work, bugfixes, refactors, or migrations. The goal is small diffs, concrete evidence, and safe handoffs when full validation isn’t possible.

How this skill works

Start by collecting inputs: repository path, task goal, constraints, risk tolerance, and validation commands. Prime the codebase by listing files and identifying entry points, then summarize where the change belongs and any ambiguities. Create a short plan with success criteria, implement the smallest viable patch, run the requested validation commands, and record results. Finish with a wrap-up that includes the patch, evidence, risks, and next steps.

When to use it

  • Implementing a feature that must minimize API or surface changes.
  • Fixing a bug where confidence and traceable validation are required.
  • Performing a focused refactor or migration with clear rollback criteria.
  • Working in a high-risk or tightly regulated codebase needing explicit verification.
  • Handing off work to another engineer and needing reproducible evidence.

Best practices

  • Keep diffs minimal: only change what’s necessary for the goal.
  • Always include validation commands and paste actual results as evidence.
  • Define explicit success criteria and exit conditions before coding.
  • Avoid broad refactors; ask for permission before expanding scope.
  • If you cannot run validations, state the limitation and propose the safest next steps.

Example use cases

  • Safe bugfix: apply a one-line logic change, run targeted tests, and document risks.
  • Feature add: add a small module-level capability with a unit test and short doc note.
  • Migration: change configuration shape in one module, validate with build and smoke tests.
  • Role-based workflow: include a test_writer and reviewer role with verification for each step.
  • Closed-loop patching: iterate request -> change -> validate until exit conditions are met.

FAQ

What do you do if validation commands fail but tests are flaky?

Record failing outputs, run a minimal repro to isolate flakiness, limit attempts per exit criteria, and summarize hypotheses and logs for the next engineer.

How large can a diff be before it violates guardrails?

There’s no fixed line count; prefer smallest viable patch. If scope grows, ask for approval and update constraints before proceeding.