sn-spec-writing

name

sn-spec-writing

description

Write technical specifications for SignNow MCP Server features. Use when designing a new feature, writing a spec, performing architecture review, or converting a feature idea into requirements. Covers the analysis protocol (philosophy check, layer check, tool design, auth, errors, testability), spec output format, and Pydantic model design. Do NOT use for implementation, testing, or planning — those have dedicated skills.

Technical Specification Writing

Analysis Protocol

Before designing any feature, run every check in order. If any check fails, reject or redesign before proceeding.

1. Philosophy Check

Principle	Question
Thin Translator	Does this maintain the stateless translation identity? If it adds state, caching, or agent-side logic — redesign.
Simplicity	Is this the simplest possible solution? Can it have fewer moving parts?
YAGNI	Is the feature actually needed now, or is it speculative?

2. Architecture & Layer Check

• Which layers are affected? Consult the layer access matrix (skill: sn-architecture).
• Upward imports (signnow_client/ → sn_mcp_server/)? → Reject.
• Tool functions importing Starlette or referencing HTTP headers? → Redesign to use TokenProvider.
• Module-level mutable state, global caches, singletons? → Reject.

3. Tool Design Check

• Does this need a new MCP tool? Can the functionality join an existing tool instead?
• If new: does it overlap with existing tools? Could one tool handle both with an internal branch?
• Are parameters minimal and clear? Can an agent use this from the docstring alone?
• Does the response model include only decision-relevant fields? No raw API passthrough.

4. Auth & Transport Check

• Works across all 3 auth strategies (password grant, bearer header, OAuth2 JWT)?
• Works across all 3 transports (STDIO, Streamable HTTP, SSE)?
• No deployment-environment assumptions?

5. Error Handling Check

• List every failure mode explicitly.
• Each failure mode: specific error message with operation name, entity ID, cause.
• SignNow API errors translated via signnow_client/exceptions.py.
• Pydantic validation errors surfaced as clear parameter-level messages before any API call.

6. Testability Check

• Business logic testable by injecting a mocked SignNowAPIClient?
• List test cases: happy path + each failure mode.
• Any tests require network calls? → Redesign.
• New tests mirror tests/unit/ source structure.

7. Documentation Check

• README.md needs updating? (New tools, auth changes, transport changes.)
• Tool docstrings concise, accurate, actionable for an AI agent?
• Tool registered in tools/__init__.py → register_tools()?

Output Style Rules

Do	Don't
Define Pydantic models as complete runnable Python (models ARE the spec)	Write function bodies or full implementations
Define function signatures with full type hints + docstrings (body = ...)	Paste raw SignNow API JSON responses
Use numbered pseudo-code for business logic flow	Reference Starlette/ASGI/HTTP in tool specs
Produce an explicit error catalog table	Skip error scenarios
Produce a test matrix table	Write actual test code

Spec Output Format

Write to .specs/Spec-{TASK_NAME}.md with these sections:

1. Business Goal & Value

One paragraph max. Include a Philosophy Check table (Thin Translator, Stateless, Tool Minimization, Token Efficiency, YAGNI, No Infrastructure Coupling — each with ✅/❌ verdict + rationale).

2. Affected Layers

Table: Layer | File(s) | Change Type | Description.

3. System Diagram (Mermaid)

Sequence diagram: Agent → Tool → Business Logic → API Client → SignNow API → Response Model → Agent.

4. Technical Architecture

• 4.1 Pydantic Models — full Python code for all new/modified models (API-level and response-level).
• 4.2 Function Signatures — full signatures with type hints, docstrings, body = ....
• 4.3 Business Logic Flow — numbered pseudo-code steps per function.
• 4.4 Error Catalog — table: Trigger | Exception Class | Message Template.

5. Implementation Steps

Ordered checkbox list. Each step = one reviewable unit.

6. Test Matrix

Table: Test Name | Input | Mocked API Behavior | Expected Output/Assertion.

7. Risk Assessment

Table: Risk | Impact | Likelihood | Mitigation.

8. File Structure Summary

Tree view of all new and modified files.