Architecture Spec Development Skill

Develop a kickass spec for a new feature using an iterative multi-pass approach with documentation fetching and code review refinement.

Note: This skill is tech-stack agnostic. When installed in a project, adapt the questions, documentation sources, and implementation guidance to match the project's specific tech stack and conventions.

Steps

Here is the requirements prompt: $ARGUMENTS

1. Clarify the requirements

First, evaluate whether the requirements document requires any clarification. If it does, ask the user before proceeding, and append the clarifications to the requirements document in a ## Clarifications section.

Unless the requirements are extremely clear upfront, you should always ask at least 3 clarifying questions - ideally, select the ones which are most likely to reduce ambiguity and result in a great spec, and, later, a great, tight implementation that does what it needs to do and nothing more.

Consider asking about:

Core functionality and expected behavior
Data models and state management approach
UI/UX requirements and user interactions
Integration points with existing systems
Performance and scalability requirements
Error handling and edge cases

2. Fetch documentation

Once you are happy with the basic requirements, decide whether it requires documentation in addition to what is present in the codebase. If it does, fetch the relevant documentation and summarize it.

Look for documentation in:

Project README and docs folder
Framework/library documentation relevant to the project
Existing patterns and conventions in the codebase
API documentation for external services

3. First iteration of the spec

Create a first iteration of the spec using an Application Architect approach. Pass it the documentation it needs as well as the requirements.

The spec should cover:

Architecture Overview: High-level structure and component relationships
Data Models: Core entities, their properties, and relationships
Component Design: Breakdown of modules/components and their responsibilities
Integration Points: How components interact with each other and external systems
Implementation Details: Specific patterns, libraries, and approaches to use

The first iteration should end up in a file named YYMMDD-XXa-spec-headline.md in a /docs/plans/ folder.

So for example, if the requirements are for a "user-authentication" feature, the first iteration of the spec should be called /docs/plans/250121-01a-user-authentication.md.

4. Refine the spec

Use the code-reviewer skill (grumpy Carlos reviewer) to review the first iteration. Channel Carlos's brutally honest but supportive style — push back hard on unnecessary complexity, unclear patterns, and over-engineering while celebrating what works well.

Review with exacting standards for:

Code quality and best practices for the project's tech stack
Proper use of established patterns and conventions
Unnecessary complexity or over-engineering
Security considerations
Performance implications

Write all review comments in a file named YYMMDD-XXa-spec-headline-review-feedback.md in the /docs/plans/ folder.

5. Second iteration of the spec

Take the first iteration of the spec, the relevant documentation, the requirements and the review comments, and create a second iteration of the spec, applying the feedback.

The second iteration should focus on:

Simplifying any over-engineered solutions
Ensuring proper use of project conventions
Removing unnecessary abstractions
Making the code clear, simple, maintainable

The second iteration should be called YYMMDD-XXb-spec-headline.md in the /docs/plans/ folder.

6. Refine the spec again

Use the code-reviewer skill (grumpy Carlos reviewer) again to review the second iteration. Apply the same high standards — be blunt, concise, and constructive. Repeat the review process for the second iteration of the spec.

7. Third iteration of the spec

Apply the second round of feedback to create the final spec iteration: YYMMDD-XXc-spec-headline.md.

8. Pause and notify the user that the spec is ready for review

The user will want to review the spec in detail before proceeding to implementation.

In your notification, summarize the key, final components of the spec at a very high level (3 paragraphs max), and also summarize the key changes that were made thanks to the review suggestions (also 3 paragraphs max). Use paragraphs rather than bullet points.

9. Afterwards: build the feature

When building the feature, follow the project's established patterns for:

File organization and naming conventions
Code style and formatting
Testing approach and coverage expectations
Documentation requirements

Once they have finished building the feature, please review the code output yourself to ensure it meets high standards and hasn't deviated substantially from the spec without good cause.

Output Format

Throughout this process, maintain clear documentation:

Spec Files: YYMMDD-XXa/b/c-spec-headline.md - Each iteration of the spec
Review Files: YYMMDD-XXa/b-spec-headline-review-feedback.md - Feedback for each iteration
Final Summary: A concise notification to the user summarizing the spec and key improvements

Remember: The goal is to create a spec that is clear, comprehensive, and actionable. Each iteration should be better than the last, with unnecessary complexity stripped away and project patterns properly applied.

architecture