Technical Spec TemplateCAUTION

1255 professional Agent Skills for Claude, ChatGPT, Gemini, Cursor & Codex — PRDs, postmortems, leases, medical bills, layoffs, go-bags, new countries. Plain markdown, MIT, in Anthropic's plugin directory. Plus a typed decision layer: which skill, is it safe, ship or slip. Free in-browser or npx pm-

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: technical-spec-template
description: "Create structured technical specification documents that bridge product requirements and engineering implementation. Use when writing a tech spec, engineering spec, system design doc, or API specification. Produces a complete spec with problem statement, proposed solution, data model, API design, alternatives considered, security considerations, testing plan, and rollout strategy."
---

# Technical Spec Template Skill

Write technical specifications that engineers actually read — clear problem framing, unambiguous requirements, explicit decisions, and documented trade-offs.

## Required Inputs

Work from what is given. If any of these is missing, still produce the complete output: fill each gap with a reasonable assumption marked *(assumed, confirm)* and list those assumptions at the end. Ask a question first only when the core subject itself is missing (there is nothing to write about).
- **Feature or system description** (what needs to be specced)
- **Related PRD or product brief** (if available)
- **Engineering reviewers** (whose sign-off is needed)
- **Known constraints** (technical limitations, security requirements, performance targets)

## When to Write a Tech Spec

Write a tech spec when:
- The feature requires changes to 2+ systems
- There are significant architectural decisions to make
- More than one engineer will work on the implementation
- The feature has security, privacy, or compliance implications
- Estimated effort is >5 story points

Skip the spec for trivial bug fixes or 1-2 hour changes.

---

## Technical Spec Output Format

### Technical Specification — [Feature Name]

**Author:** [Name]
**Status:** Draft | In Review | Approved | Implemented
**Created:** [Date] | **Last Updated:** [Date]
**Reviewers:** [Eng Lead, Architect, PM, Security if needed]
**Related PRD:** [Link] | **Jira Epic:** [Link]

---

#### 1. Problem Statement
> [2–3 sentences. What problem are we solving and why now? No solution language here.]

#### 2. Goals & Non-Goals

**Goals (in scope):**
- [Specific, measurable outcome]
- [Specific, measurable outcome]

**Non-Goals (explicitly out of scope):**
- [What this spec does NOT cover]
- [Common assumption to shut down early]

#### 3. Background & Context
[Any prior art, related systems, or context engineers need to understand the decision space. Link to previous specs, ADRs, or research.]

#### 4. Proposed Solution

**High-Level Approach:**
[2–4 sentences describing the chosen solution. Why this approach vs alternatives?]

**System Architecture Diagram:**
[Describe or embed: which services are involved, how data flows, what APIs are called]

**Data Model Changes:**
```sql
-- New tables or schema changes
[Include DDL or schema definition]
```

**API Design:**
```
[Endpoint] [Method]
Request: { [fields and types] }
Response: { [fields and types] }
Error codes: [list]
```

**Key Implementation Details:**
- [Important technical constraint or approach]
- [Edge case handling]
- [Third-party dependency and version]

#### 5. Alternative Approaches Considered

| Option | Pros | Cons | Why Rejected |
|---|---|---|---|
| [Alt 1] | [Benefits] | [Drawbacks] | [Reason not chosen] |
| [Alt 2] | [Benefits] | [Drawbacks] | [Reason not chosen] |

#### 6. Security & Privacy Considerations
- Data stored: [What PII or sensitive data is involved]
- Authentication: [How is access controlled]
- Authorisation: [What permissions are required]
- Encryption: [At rest / in transit requirements]
- Compliance implications: [GDPR, SOC2, etc. if relevant]

#### 7. Performance & Scalability
- Expected load: [Requests/second, data volume]
- Latency requirements: [P50 / P95 targets]
- Caching strategy: [If applicable]
- Database indexing: [New indexes required]
- Known bottlenecks: [Where to watch]

#### 8. Testing Plan
- Unit tests: [Key scenarios to cover]
- Integration tests: [System boundaries to test]
- Load tests: [If performance-critical]
- Edge cases: [Known tricky scenarios]
- Rollback plan: [How to revert if something goes wrong]

#### 9. Rollout Plan
- Feature flag: [Yes / No — name of flag]
- Rollout stages: [% of users at each stage]
- Monitoring: [Metrics and alerts to set up]
- Success criteria to progress rollout: [What needs to be true]
- Rollback trigger: [What would cause immediate rollback]

#### 10. Open Questions
| Question | Owner | Due Date | Resolution |
|---|---|---|---|
| [Unresolved question] | [Name] | [Date] | [Pending] |

#### 11. Implementation Timeline (Rough)
| Phase | Work | Estimated Effort |
|---|---|---|
| [Phase 1] | [What gets built] | [X days/points] |
| [Phase 2] | [What gets built] | [X days/points] |
| Total | | [X story points] |

---

## Guidelines

- The spec is a decision record, not a task list — document *why* decisions were made
- All open questions must have an owner and due date
- Security and privacy sections are never optional for features that touch user data
- Recommend async review: engineers read first, then a 30-minute sync to resolve questions
- Keep the spec updated as implementation progresses — stale specs are worse than no specs

## Deeper Materials

This skill ships with support files — use them when they are available:

- **`references/spec-decisions.md`** — What a Spec Is For: Decisions, Alternatives, and the Blast Radius. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
- **`templates/spec-skeleton.md`** — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.

## Scoring Rubric (0–40)

Score any output of this skill before handing it over; 32+ is ship-quality.

| Dimension | 0 | 5 | 10 |
|---|---|---|---|
| Problem framing | Problem statement is the solution restated ("we need a queue"), or missing; no non-goals | Problem stated but with solution language leaking in; non-goals present but generic 

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

templates/pm-discovery-agent/skills/assumption-mapper/SKILL.md

templates/pm-discovery-agent/skills/discovery-interview-guide/SKILL.md

templates/pm-discovery-agent/skills/job-story-mapper/SKILL.md

templates/pm-discovery-agent/skills/user-interview-synthesis/SKILL.md

templates/pm-launch-agent/skills/content-calendar/SKILL.md

Gates applied: no_behavioural_pass.