Skip to content

im-shashanks/claude-plugins / shaktra/skills/shaktra-reference

shaktra-reference

Verified

Shared constants, quality standards, and state schemas for all Shaktra agents. Defines severity taxonomy, quality principles, guard tokens, review dimensions, and YAML schemas.

quality-principles.md

View on GitHub
# Quality Principles

11 core principles for all Shaktra agents. Each principle has 2 verification checks — concrete questions to confirm the principle is met.

## 1. Correct Before Fast

Write code that produces the right result first. Optimize only after correctness is proven by tests.

- **Verify:** Do all tests pass with the current implementation?
- **Verify:** Were any shortcuts taken that trade correctness for speed?

## 2. Fail Explicitly

Never swallow errors silently. Every failure must be surfaced, logged, or propagated with context.

- **Verify:** Does every catch/except block either re-raise, log, or return a meaningful error?
- **Verify:** Can a caller distinguish success from failure without inspecting side effects?

## 3. Test Behavior, Not Implementation

Tests should assert what the code does, not how it does it. Refactoring internals should not break tests.

- **Verify:** Would renaming a private method or changing internal data structures break any test?
- **Verify:** Does each test describe a behavior a user or caller cares about?

## 4. One Responsibility Per Unit

Each function, class, or module should have a single reason to change.

- **Verify:** Can you describe what this unit does in one sentence without "and"?
- **Verify:** Would a change to an unrelated feature require modifying this unit?

## 5. Inject External Dependencies, Own State

Accept external collaborators (services, I/O, clocks) from the outside; manage your own internal state. Inject what you'd replace in tests. Construct internal utilities directly.

- **Verify:** Can every external dependency be replaced with a test double without modifying the unit?
- **Verify:** Does the unit avoid global mutable state, and avoid injecting stable utilities it will never swap?

## 6. Handle Every Error Path

Every operation that can fail must have an explicit error path — no implicit assumption of success.

- **Verify:** For each I/O call, network request, or parse operation, is there an error handler?
- **Verify:** Are error paths tested, not just the happy path?

## 7. Log Structured, Trace Distributed

Use structured logging (key-value pairs) and propagate correlation IDs across service boundaries.

- **Verify:** Are log entries structured (not interpolated strings) with consistent field names?
- **Verify:** Do cross-service calls propagate a trace/correlation ID?

## 8. Bound All Resources

Every pool, queue, buffer, timeout, and retry must have an explicit upper bound.

- **Verify:** Does every network call have a timeout configured?
- **Verify:** Are queues, pools, and buffers capped with explicit max sizes?

## 9. Make It Work, Make It Right, Make It Fast

Follow the sequence: get it working with tests, clean up the design, then optimize with profiling data.

- **Verify:** Were all tests green before any refactoring or optimization began?
- **Verify:** Is any optimization backed by measured profiling data rather than intuition?

## 10. Document Every Tradeoff

When choosing between alternatives, record what was chosen, what was rejected, and why.

- **Verify:** Is there a decision record for each non-obvious architectural or design choice?
- **Verify:** Does the record state at least one rejected alternative and the reason for rejection?

## 11. Keep Behavior Local

Code that changes together should live together. A unit is debuggable when a reader can understand its full behavior without opening other files.

SRP says split when two things have different reasons to change. Locality says don't split when a reader needs both halves to understand either one. Splitting purely for "cleanliness" creates indirection that costs more at 3 AM than it saves at code-review time.

- **Verify:** Can you understand what this function does — including its error paths — without jumping to other files?
- **Verify:** Does the split between units reduce cognitive load, or just distribute it across more files?
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall