@aayushchugh/skills 0.1.1 → 0.1.3

package/README.md

@@ -29,10 +29,11 @@ Replace `no-slop` with any id below.
 
 - `no-slop` — No slop. Write the smallest readable code that reuses existing code, installed utilities, and repo patterns, and fixes bugs at the root cause.
 - `plain-paper` — Plain paper. Write a spec or other documentation from the request, the code, and relevant sources.
-- `cases-to-run` — Cases to run. Write a small, risk-based set of test cases from a spec, diff, or bug report.
+- `cases-to-run` — Cases to run. List the cases to verify by hand, or name the code tests for `no-slop` to write when asked.
 - `open-doors` — Open doors. Review application code, APIs, dependencies, secrets, and deploy config for injection, web attacks, and DDoS controls.
 - `one-shape` — One shape. Audit a repo for duplication, divergent flows, dead code, over-engineering, waste, and standards drift, then apply approved steps.
 - `red-pen` — Red pen. Review a diff or pull request for bugs, regressions, broken callers, missing tests, and unmet requirements.
 - `the-cause` — The cause. Find a bug's root cause from the report, the code path, and the evidence.
 - `go-or-stop` — Go or stop. Decide if a change is ready to ship, with a go or no-go, what to watch, and how to roll back.
+- `the-map` — The map. Map, propose, or improve a system's design like a senior engineer, grounding the recommendation in real usage and activity.
 - `which-skill` — Which skill. Pick and run the right skill, or a chain of skills, for a request.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aayushchugh/skills",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "The agent skills I use while building real products.",
 	"author": "Ayush Chugh <hey@ayushchugh.com>",
 	"license": "MIT",

package/skills/cases-to-run/SKILL.md

@@ -1,16 +1,18 @@
 ---
 name: cases-to-run
 description: >-
-  Write a small, risk-based set of test cases from a spec, diff, or bug
-  report. Use when the user asks for test cases or QA coverage. Do not write
-  test code or audit security.
+  List cases to verify by hand, or name the code tests for no-slop when
+  asked. Use when the user asks for test cases or to test a flow. Do not edit
+  code or audit security.
 ---
 
 # Cases to run
 
 ## Scope
 
-Write the test-case document only. Do not write test code, run tests, or change the source. Cover a security requirement or access rule the source already states. Do not invent controls.
+Do not edit code. `no-slop` is the only skill that writes. Do not write anything until asked. Cover a security requirement or access rule the source already states. Do not invent controls.
+
+Write the smallest set that would catch a real failure. Skip a case that does not change the outcome.
 
 ## Before writing
 
@@ -24,41 +26,33 @@ Ask what would change the expected behavior, data, environment, limits, or permi
 - Code or a diff: the changed behavior, its contract, its callers, and the conditions that changed. Stop at the affected path.
 - A bug report: the shortest reproduction, expected versus actual behavior, and the environment when it changes the result.
 
-If the repository already tests a behavior, cite that test. Do not write a duplicate manual case.
+If the repository already tests a behavior, say so. Do not ask `no-slop` to add a second copy, and do not repeat it as a manual case.
 
 ## Which cases
 
 Cover the relevant happy path, failure, boundary, state change, permission, and regression. Use one representative value per equivalence class. A boundary is the edge: the last allowed value and the first rejected value.
 
-Test one invalid condition at a time. Combine inputs only when they change the outcome together. One behavior is one case, even when the spec and the code both mention it. Cite both sources on that case.
+Test one invalid condition at a time. Combine inputs only when they change the outcome together. One behavior is one case, even when the spec and the code both mention it.
 
 Skip a behavior the spec lists as a non-goal. A missing P0 behavior gets a case, or an open question that says why it cannot be tested yet.
 
 A bug gets one regression case: it fails on the current behavior and passes once the expected behavior is true. A state flow gets the valid path plus the invalid transitions a person can actually attempt.
 
-## Priority
+## The list
 
-Order the document P0, then P1, then P2.
+The default is a bullet list to verify by hand. Order it P0, then P1, then P2. Each bullet is the behavior and the expected result.
 
 - P0: data loss, money, access, a broken primary flow, or an existing caller that would regress.
 - P1: a common failure or a boundary.
 - P2: a rare edge.
 
-## Each case
+## Code tests
 
-- ID
-- Title
-- Source requirement or changed behavior
-- Priority
-- Preconditions: role, starting data, and starting state
-- Test data
-- Steps: actions only. Do not repeat the expected result.
-- Expected result: only what a person can see, including the error, the resulting state, and data that must stay unchanged
-- Tags: `happy`, `failure`, `boundary`, `permission`, or `regression`. Use one only when it applies. Use no other tag.
+Write code tests only when the user asks for them. Name the behaviors. `no-slop` writes the test in the repo's existing style. If the repo has no test runner, ask once before `no-slop` adds one.
 
 ## Summary
 
-Counts by priority. Each source requirement or changed behavior mapped to case IDs. Anything left uncovered. Then assumptions and open questions. Do not add a matrix. Do not claim complete coverage when the source is ambiguous.
+Counts by priority, and anything left uncovered. Do not claim complete coverage when the source is ambiguous.
 
 ## Replies
 

package/skills/go-or-stop/SKILL.md

@@ -11,6 +11,8 @@ description: >-
 
 Read the diff, the test results, the migrations, the feature flags, the dependency changes, the deploy config, and the known risks. Do not deploy, change production, or create a release until the user explicitly approves that step.
 
+No-go when a migration check or a rollback is missing. A failed or missing test result is a no-go only when the repo already has test code. A repo with no test code skips that check. Do not talk the release into a go.
+
 ## Before writing
 
 Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
@@ -20,7 +22,7 @@ Ask the target environment, the migrations included, and the checks already run.
 ## The check
 
 - What changed, in one line per user-facing change. Leave out internal refactors.
-- Tests: which ran, which failed, and which did not run.
+- Tests, when the repo has test code: which ran, which failed, and which did not run. A repo with no test code skips this check.
 - Migrations and backfills. Each one needs the current state (table, row count, rows touched), the forward change, a rollback or the data that would be lost, steps that are safe to re-run, batching for a large table, and a check that proves the result. A migration missing any of these is a no-go.
 - Feature flags and dependency changes.
 - Known risks, each with the check that would catch it.
@@ -33,7 +35,7 @@ Ask the target environment, the migrations included, and the checks already run.
 - The rollback steps, in the order to run them.
 - A short note of what changed for users.
 
-A missing test result, a migration missing any item above, or an unknown rollback is a no-go. Do not invent a test result.
+A migration missing any item above, or an unknown rollback, is a no-go. A missing test result is a no-go only when the repo has test code. Do not invent a test result.
 
 ## Replies
 

package/skills/no-slop/SKILL.md

@@ -12,6 +12,8 @@ description: >-
 
 Code only. Product docs, PRDs, and other non-code writing are out of scope. On a review, apply these rules to the diff and do not edit unless asked.
 
+Refuse a layer, abstraction, or dependency the current code does not need.
+
 ## Before editing
 
 Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
@@ -25,7 +27,7 @@ Ask only what would change the requested files, behavior, API, or approach. Leav
 3. Prefer, in order: do nothing, existing code, the standard library, a native platform feature, an already-installed dependency. If that dependency exports the function, call it. Do not rewrite date-fns, lodash, or any other installed package.
 4. Make the smallest readable change that finishes the requested behavior. A bug report names a symptom. Find the source and fix that. A shared-function fix keeps existing callers working, unless their current behavior is the bug.
 5. Keep trust-boundary validation and error handling that prevents data loss.
-6. Run the repo's existing test for the changed path. Add one small check only when that path has no test and the branch is non-trivial.
+6. Run the existing test for the changed path when one exists. If the project has no test code, do not add one and do not block. Write a test only when `cases-to-run` or the user asks.
 
 ## Rules
 

package/skills/one-shape/SKILL.md

@@ -12,6 +12,8 @@ description: >-
 
 The audit is read-only until the user approves a batch. Then apply one step at a time with `no-slop`.
 
+Make the smallest change that removes the drift. Do not add an abstraction a third copy does not force.
+
 Skip code the team does not own: `node_modules`, build output, generated files, vendored code, lockfiles, and migrations. A security issue gets one line pointing to `open-doors`.
 
 ## Before auditing
@@ -52,11 +54,11 @@ Mark each step's effort and risk as low, medium, or high.
 
 Order the steps: delete dead code, then replace reimplemented code, then fix standards drift, then unify flows, then simplify what is left. A formatting-only change is its own step and uses the repo's formatter. Never mix it with a logic change.
 
-Each step is small, keeps behavior the same, ships on its own, names its files, and names the test that checks it. When no test covers a step, say so and use `cases-to-run` before that step. A merge keeps every current caller's output the same. If any caller's output would change, that needs its own approved step. On a big repo, the user approves one batch at a time.
+Each step is small, keeps behavior the same, ships on its own, names its files, and names the test that checks it when one exists. A repo with no test code does not block a step. A merge keeps every current caller's output the same. If any caller's output would change, that needs its own approved step. On a big repo, the user approves one batch at a time.
 
 Stop after the report. Edit nothing until the user approves a batch.
 
-1. Before the first step, run the repo's lint, typecheck, and tests, and record what already fails.
+1. Before the first step, run the repo's lint, typecheck, and tests when the repo has them, and record what already fails.
 2. Apply one approved step at a time with `no-slop`. Each step stays its own diff.
 3. After each step, run the same checks. If a new failure appears, revert that step, stop, and report.
 4. After a batch, re-check the remaining steps, then wait for the next approval.

package/skills/open-doors/SKILL.md

@@ -14,6 +14,8 @@ Review application code, APIs, dependencies, secrets, and deployment configurati
 
 This is a read-only audit, not active pentesting. Do not send probes, payloads, traffic, or requests to a live target. Do not claim a control works unless repository evidence proves it. Do not edit the source.
 
+Report a gap a person can actually reach. A theoretical issue with no evidence is not a finding.
+
 ## Before writing
 
 Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.

package/skills/plain-paper/SKILL.md

@@ -14,10 +14,12 @@ A spec describes what will be built. Documentation describes what exists.
 
 - A PRD says what and why. It does not choose the implementation.
 - An engineering spec says how the system behaves: interfaces, data, failure, trade-offs, rollout, and verification.
-- Documentation covers a flow, API reference, architecture note, runbook, onboarding guide, README, changelog, user guide, or another document the user names.
+- Documentation covers a flow, API reference, runbook, onboarding guide, README, changelog, user guide, or another document the user names. An architecture note, a system design, or a scale or performance review goes to `the-map`.
 
 Code changes are out of scope. A security need is one requirement. Do not invent controls or run an audit.
 
+Write the short document a person can build or follow. Leave out a section that does not change a decision.
+
 ## Before writing
 
 Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.

package/skills/red-pen/SKILL.md

@@ -12,7 +12,9 @@ description: >-
 
 Read the diff, the request it was meant to satisfy, every caller of a changed function, and the tests that cover the path. For a pull request, read the diff with `gh pr diff`. Do not edit the code.
 
-A security finding gets one line pointing to `open-doors`. A structure or duplication finding gets one line pointing to `one-shape`. A missing test gets one line pointing to `cases-to-run`.
+Report a bug, a regression, or a missed requirement. A style comment is not a finding.
+
+A security finding gets one line pointing to `open-doors`. A structure or duplication finding gets one line pointing to `one-shape`. A missing test is a finding only where the project already tests that kind of path. A project with no tests gets one line pointing to `cases-to-run`, not a finding per file.
 
 ## Before writing
 
@@ -22,7 +24,7 @@ Ask what would change whether a finding is real.
 
 ## Findings
 
-Report a correctness bug, a regression, a break in an API a caller depends on, a missing test for a changed path, or a requirement the change did not meet.
+Report a correctness bug, a regression, a break in an API a caller depends on, a missing test where the project already tests that kind of path, or a requirement the change did not meet.
 
 Each finding has: ID, Title, Severity, File and line, Evidence, Impact, Fix in one or two lines.
 
@@ -32,7 +34,7 @@ One finding per root cause. The same bug in several callers is one finding: name
 
 - Critical: the change loses data, breaks a primary flow, or breaks callers that are already in use.
 - High: a real bug on a common path, or a requirement the change missed.
-- Medium: a bug that needs another condition, or a missing test on a non-trivial branch.
+- Medium: a bug that needs another condition, or a missing test on a non-trivial branch where the project already has tests.
 
 ## Summary
 

package/skills/the-cause/SKILL.md

@@ -12,6 +12,8 @@ description: >-
 
 Read only the path the bug touches, its callers, and the logs, traces, or connected sources needed to prove the cause. Do not edit the code. The fix goes to `no-slop`. The regression case goes to `cases-to-run`.
 
+Name the source. A local workaround is not a cause, and a cause without evidence stays a hypothesis.
+
 ## Before writing
 
 Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.

package/skills/the-map/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: the-map
+description: >-
+  Map, propose, or improve a system's design like a senior engineer,
+  grounding the recommendation in real usage and activity. Use when the user
+  asks for a system design, architecture review, or scale or performance
+  improvement. Do not write code.
+---
+
+# The map
+
+## Scope
+
+Writes the design. Does not change code. A PRD or engineering spec stays with `plain-paper`. Building an approved change stays with `no-slop`, and only after the user approves.
+
+Write as a senior engineer: recommend the smallest design that fits the evidence, name the trade-off of what you did not choose, and never reach for a pattern the evidence does not justify.
+
+## Before writing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+Ask which mode when the request does not say:
+
+- **As it is.** Read the repo: entry points, callers, routes, data stores, integrations, and deploy config. Every component cites a file. An unknown part goes under Open questions.
+- **A proposal.** Ask the constraints that would change the design: scale, what already exists, and what must not change. Recommend one design. Name the trade-off and what was not chosen, in one line. Do not invent users, scale, or a deadline.
+- **An improvement.** Read the current design from the code first. Then gather real usage and activity: traffic, growth, hot paths, read/write ratio, latency, error rate, and cost. Read what the repo already exposes for this: logging and metrics code, dashboard config, APM setup. Ask the user for a number the repo does not show. Do not estimate a number neither source gives; put it under Open questions.
+
+## The document
+
+Use only the sections that apply: the job, the components and what each owns, the request path, where data lives, what failure loses or retries, what sits outside the system, the trade-off, and open questions.
+
+For an improvement, add: the evidence read, each proposed change tied to the evidence that justifies it, and a priority of P0, P1, or P2.
+
+- P0: a risk the evidence shows is already happening.
+- P1: a real but smaller gap.
+- P2: polish.
+
+A change with no cited evidence is not proposed. A security need is one line pointing to `open-doors`.
+
+## Replies
+
+Say which mode you used, and what is still open or unconfirmed.

package/skills/which-skill/SKILL.md

@@ -7,6 +7,10 @@ description: >-
 
 # Which skill
 
+## Scope
+
+Run one skill when one fits. Do not start a chain to look thorough.
+
 ## Before writing
 
 Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
@@ -19,12 +23,13 @@ Read the chosen skill and follow it. Do not restate its rules here.
 | --- | --- |
 | Implement, fix, or review code | `no-slop` |
 | PRD, engineering spec, flow, API reference, runbook, guide, or README | `plain-paper` |
-| Test cases or regression coverage | `cases-to-run` |
+| Manual test cases, or code tests for `no-slop` when asked | `cases-to-run` |
 | Security audit | `open-doors` |
 | Refactor or clean up a repo | `one-shape` |
 | Review a diff or pull request | `red-pen` |
 | Diagnose or debug a failure | `the-cause` |
 | Release check or go / no-go | `go-or-stop` |
+| System design, architecture review, or scale/performance improvement | `the-map` |
 
 Run one skill when one fits. Say which skill or chain you picked in one line. Ask one question when two skills fit equally.
 
@@ -36,5 +41,6 @@ Pause for approval before a step that writes code or would deploy.
 - Feature: `plain-paper` as a spec, then `no-slop`, then `red-pen`.
 - Release: `red-pen`, then `go-or-stop`. A migration is covered inside `go-or-stop`.
 - Cleanup: `one-shape`, which applies its changes through `no-slop`.
+- Design: `the-map`, then `plain-paper` if a spec is still needed, then `no-slop` after approval.
 
-`go-or-stop` does not deploy. `one-shape` does not edit until a batch is approved.
+`go-or-stop` does not deploy. `one-shape` does not edit until a batch is approved. `the-map` does not write code.