It should make a pre-plan brief that explains:
The objective of this phase is NOT to implement the application. The objective is to perform research, requirements gathering, standards discovery, architectural analysis, and produce complete implementation specifications before coding begins.
and summarize:
- Project Title
- What We Are Designing
- Research-First Instructions
- Product Goals
- Desired Capabilities
- Preferred Technical Direction, if any
- Architectural Constraints
- Explicit Non-Implementation Instruction
- Recommendation Rules
- Known Unknowns
The Pre-Plan Brief skill should ask only enough questions to generate this brief such as:
- What are we designing?
- Is this desktop, web, mobile, CLI, library, or service?
- What capabilities should be considered?
- Are there preferred technologies?
- Are there technologies we should avoid?
- What assumptions are already known?
The Pre-Plan Brief skill should classify readiness based on whether it can generate a useful Spec Project Brief:
- NOT READY: cannot describe what is being designed.
- PARTIALLY READY: can describe the project, but missing goals/capabilities/constraints.
- READY FOR SPEC BRIEF: enough information to generate the brief.
- READY FOR DISCOVERY: enough information to begin research and specification generation.
Save Pre-Plan Brief to plans/preplan-brief.md. Then produce specification documents in plans/specs and research documents in plans/research such as:
- Requirements Specification -
plans/specs - Functional Specification -
plans/specs - Architecture Specification -
plans/specs - Security Specification -
plans/specs - Data Model Specification -
plans/specs - UX Specification -
plans/specs - Implementation Roadmap -
plans/roadmap - Risk Analysis -
plans/reviews - Open Questions and Research Gaps -
plans/reviews
Act as a principal engineer, architect, security reviewer, product manager, and skeptical CTO.
Review all generated specifications.
Challenge assumptions.
Identify risks.
Identify missing requirements.
Identify scaling concerns.
Identify security concerns.
Identify alternative architectures.
Identify lock-in risks.
Identify future migration risks.
Ask difficult questions.
Do not propose implementation yet.
Produce a review document.
Review all specifications, architecture documents, review notes, gap analyses, and design discussions.
Identify every significant architectural, product, security, operational, and technical decision that has been made either explicitly or implicitly.
For each decision:
- Determine whether the decision is final, provisional, or unresolved.
- Explain the context that led to the decision.
- Identify alternatives considered.
- Identify alternatives that should be considered.
- Document tradeoffs.
- Document consequences.
- Identify follow-up questions.
- Recommend whether an ADR should be created.
Generate:
1. ADR Candidate List
2. Proposed ADR Priority Order
3. Draft ADR documents for all high-priority decisions `plans/adr`
Do not invent decisions that are not supported by the source documents.
Highlight any decisions that appear inconsistent across documents.
Act as a principal architect.
Review all ADRs.
For each ADR:
- Challenge the decision.
- Present the strongest argument against it.
- Identify future migration risks.
- Identify lock-in risks.
- Identify operational risks.
- Identify scaling risks.
- Identify maintenance risks.
Do not defend the current architecture.
Actively attempt to find flaws.
Generate an Architecture Review Report.
What information is still missing before implementation can begin? put in `plans/decisions/implementation-readiness-gaps.md`
Review:
plans/reviews/*
plans/adr/*
plans/specs/*
Identify all unresolved questions, risks, assumptions, and architecture uncertainties.
Create a research spike document for every significant unresolved item.
Write the results to:
plans/spikes/
Naming convention:
SPIKE-001-title.md
SPIKE-002-title.md
SPIKE-003-title.md
Each spike must contain:
# Objective
# Context
# Questions To Answer
# Hypothesis
# Investigation Plan
# Success Criteria
# Decisions Unlocked
# Estimated Effort
Research spikes are learning artifacts.
Do not generate implementation tasks.
Only generate validation and research work.
Review all ADRs.
Generate:
plans/decisions/finalized-decisions.md
plans/decisions/unresolved-decisions.md
plans/decisions/deferred-decisions.md
For each decision:
- summary
- status
- rationale
- affected documents
- next action
This document should act as the executive summary of all ADRs.
Review:
plans/research/*
plans/specs/*
plans/reviews/*
plans/adr/*
plans/spikes/*
Assume all research and design work is complete.
Determine the smallest useful product that can be shipped and validated.
Challenge every feature.
Every feature must justify its inclusion in MVP.
Classify features as:
- MVP
- V1
- V2
- Future
- Remove
Generate the following documents:
plans/mvp/mvp-scope.md
plans/mvp/mvp-user-journeys.md
plans/mvp/mvp-success-metrics.md
plans/mvp/mvp-validation-plan.md
The MVP documents should include:
- included features
- excluded features
- user journeys
- architecture required for MVP
- validation goals
- measurable success criteria
- technical risks
- assumptions being tested
Optimize for learning and validation rather than completeness.
Assume engineering resources are constrained.
Prefer the smallest architecture that can validate the product thesis.
Review all project artifacts:
- plans/research/*
- plans/specs/*
- plans/adr/*
Generate acceptance criteria for all MVP-relevant systems.
Create:
plans/acceptance/
and generate one acceptance document per major system.
At minimum consider:
- [refer to `plans/specs`]
- Project Management
- Sessions
- Security and Permissions
- Settings and Configuration
Use the following structure:
# Overview
# Success Criteria
# Functional Acceptance Criteria
# Security Acceptance Criteria
# Performance Acceptance Criteria
# User Experience Acceptance Criteria
# Failure Conditions
# Out Of Scope
Use measurable and testable language.
Avoid implementation details.
Every acceptance criterion should be objectively verifiable.
Format criteria using:
Given
When
Then
or
Requirement
Expected Result
Acceptance criteria should represent the minimum standard required before a feature can be considered complete.
Review all project artifacts:
- plans/research/*
- plans/specs/*
- plans/adr/*
- plans/roadmap/*
Generate a Non-Goals document.
The purpose of this document is to explicitly define what the project will NOT do.
Identify:
- features intentionally excluded from MVP
- features intentionally deferred
- architectural approaches rejected
- technologies rejected
- standards rejected
- integrations rejected
- future ideas that should not influence current implementation
For every non-goal include:
# Item
# Why It Is Not Included
# Risks Of Including It
# Conditions Under Which It May Be Reconsidered
Classify items as:
- Never
- Not MVP
- Future Consideration
- Research Required
Examples:
- Custom Agent Runtime
- Cloud Synchronization
- Team Collaboration
- Multi-Tenant SaaS
- Proprietary Skill Format
- Proprietary MCP Protocol
- Electron Desktop Application
- Custom Model Provider Layer
The goal is to prevent scope creep and protect architectural decisions.
Be aggressive.
If a feature does not directly contribute to validating the product thesis, it should likely be classified as a non-goal.
see: https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs
save to: plans/reviews/final-implementation-readiness-review.md
Review all grill session outputs in `plans/reviews/final-implementation-readiness-review.md`.
Resolve all BLOCKER findings.
Resolve all HIGH findings.
For each finding:
- Accepted
- Rejected
- Deferred
Update ADRs and specifications as needed.
Produce a final decision summary.
`plans/decisions/`
├── `finalized-decisions.md`
├── `unresolved-decisions.md`
└── `deferred-decisions.md`
Review:
- MVP documents
- Acceptance criteria
- ADRs
- Final review
Generate a final MVP definition in `plans/mvp/mvp-freeze.md`.
This document becomes the implementation contract.
Features not listed are considered out of scope.
Convert the MVP into implementation epics in `plans/implementation/`.
Each epic must:
- map to MVP requirements
- map to acceptance criteria
- identify dependencies
- identify deliverables
Generate:
- Epic List
- Epic Dependencies
- Recommended Build Order
For each epic:
Generate implementation tasks.
Requirements:
- "independently completable"
- "testable"
- "small enough for a coding agent"
- "linked to acceptance criteria"
Include:
- "complexity"
- "dependencies"
- "completion criteria"
Given all tasks and dependencies, generate:
Sprint 1
Sprint 2
Sprint 3
Prioritize architecture validation before feature completeness.
Actual code implementation should be explicitly blocked until plans are complete. The lifecycle skill should orchestrate the workflow:
Intake → Discovery → Specifications → Acceptance Criteria → Non-Goals → Review / Grill Session → ADRs → Spikes → Decision Consolidation → MVP Freeze → Implementation Planning → Backlog Generation
The lifecycle skill must explain when to stop looping and when to implement.
All skills must follow these rules:
- Do not invent requirements.
- Do not assume the architecture.
- Do not generate implementation tasks before MVP freeze.
- Do not create specs from vague product ideas.
- Do not treat assumptions as decisions.
- Do not skip intake.
- Do not over-document low-confidence ideas.
- Prefer questions over fake completeness.
- Prefer small documents over bloated documents.
- Mark uncertainty clearly.