gjalla-spec-review
gjalla-spec-review conducts a systematic evaluation of technical specifications and plans across six expert dimensions: architecture alignment, security posture, test coverage quality, user experience viability, governance compliance, and documentation standards. Use this skill before implementation begins to identify gaps, architectural misalignments, security vulnerabilities, and testing shortfalls that could create downstream problems for engineering teams.
git clone --depth 1 https://github.com/gjalla/engineering /tmp/gjalla-spec-review && cp -r /tmp/gjalla-spec-review/skills/gjalla-spec-review ~/.claude/skills/gjalla-spec-reviewSKILL.md
# Comprehensive spec-review The best, most elegant and effective software systems are ones that are well-informed, well-planned, and verifiable. The final output is a plan/spec that can act as a reference doc, covering the problem/motivation, technical approach, deltas (what properties of the system will change once implemented), and verification criteria. Your task is to review this spec from multiple expert perspectives to ensure that this spec meets our expectations and will result in solid implementations once it's in the hands of the engineers: ## Architect Review - Does the design fit the existing system and respect layer boundaries? - Are new components placed in the correct layer and ownership hierarchy? - Do interactions follow established patterns (sync/async/event)? - Is it compatible with the broader system (i.e. cross repository integrations, future goals, etc.?) - Is it overengineered or introducing complication that will be difficult to understand/maintain? - gjalla holds the master architecture spec, referencing it is key to ensuring that we're building an elegant and effective system ## Security Review - Are all new endpoints authenticated and authorized? - Does the data model handle sensitive data correctly (PII, secrets)? - Are inputs validated at the surface-area boundary? - Are the data flows changing in a way the user should know about, like different types of data flowing to new consumers, etc.? ## Quality Review - Is the testing strategy sufficient for the behavioral requirements? - The goal for AI-generated code is typically 100% test coverage, are positive, negative, and edge cases covered? Are appropraite and effective integration tests scope based on the end-goals? - Do acceptance criteria map to testable assertions? ## User Advocate Review - Does the feature solve the stated problem? - Are failure modes graceful from the user's perspective? - Is the feature discoverable and documented? ## Governance Review - Does the spec comply with all active project rules and conventions? (gjalla's master spec also defines rules and processes, check those) - Are any rule exceptions or overrides needed? - Does this change warrant an architecture decision record (ADR)? (not all do, mostly just things that introduce significant, new tradeoffs and need a historical record) ## Output For each lens, report: what passes, what's at risk, and concrete changes required before implementation. Separate **blocking** concerns from **recommendations**.
Create a commit attestation for your changes
Load architecture context for this repo
Master-spec delta — what changes in the system when this merges
Show recent semantic change history
Review a spec OR a code change against master spec, rules, and production readiness
Initialize gjalla in this repo
Break a feature spec into intentional waves and bite-sized tasks grouped by dependency. Use after a spec is written to prepare for easy-to-track implementation.
Review a code change (diff or PR) for ship-readiness before merge. Use when reviewing your own or someone else's changes prior to committing/merging/etc.