1---
2name: codebase-singularity
3description: "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."
4metadata:
5 source: https://skillmd.com/skills/vishalsachdev/codebase-singularity
6---
7
8# Codebase Singularity
9
10## Quick start
111. Collect inputs: repo path, goal, constraints, risk tolerance, and validation commands.
122. Prime: list files, read README, and inspect entry points.
133. Summarize: explain repo shape and where the change belongs; ask questions if ambiguous.
144. Plan: write a short plan with success criteria and validation steps.
155. Change: implement the smallest viable patch; avoid unrelated refactors.
166. Validate: run the requested command(s) or the closest available; record results.
177. Wrap up: report changes, evidence, risks, and next steps.
18
19## Inputs
20- Repo path and task goal.
21- Constraints (files to avoid, time or risk limits, API stability).
22- Validation commands (tests, lint, build, or targeted checks).
23
24## Outputs
25- Short plan with success criteria.
26- Minimal patch.
27- Evidence: commands run and results.
28- Wrap-up: what changed, why, risks, and next steps.
29
30## Grades (maturity ladder)
31
32### Grade 1: Prime only
33- Prime, summarize, and stop on ambiguity.
34
35### Grade 2: Specialized roles + verification
36- Add role prompts (e.g., test_writer, docs_fetcher, reviewer).
37- Require a verification step for each role.
38
39### Grade 3: Tooling expansion
40- Declare required tools or services and expected outputs.
41- Prefer tools over guessing (e.g., query schema instead of inferring).
42
43### Grade 4: Closed-loop autonomy
44- Run cycles: request -> validate -> resolve.
45- Add hard exits: max iterations, evidence of progress, stop after repeated failures.
46
47## Guardrails
48- Keep diffs small.
49- Always validate; if you cannot, say so and propose a safe next step.
50- Ask before broad refactors or scope expansion.
51
52## Templates
53
54### Safe bugfix
55```
56Goal: Fix <bug> with minimal change.
57Constraints: Do not modify public API; avoid touching <paths>.
58Validation: Run `...` and paste output.
59Exit conditions: Stop after 2 failed attempts; summarize hypotheses and logs.
60Deliverables: Patch + explanation + risks.
61```
62
63### Add a feature
64```
65Goal: Add <feature>.
66Constraints: Keep scope to <module>; no new dependencies.
67Validation: Run `...`.
68Deliverables: Patch + tests + short doc update.
69```
70
71## References
72- Read `references/video.md` for a concise source summary.
73- Read `references/transcript.md` for full context.
74- Read `references/visual-notes.md` for a visual outline.