By Glue Team

Glue for Spec Writing

Writing a spec is hard. You must:

1. Understand current architecture and how changes fit
2. Identify dependencies and affected systems
3. Anticipate edge cases and integration points
4. Estimate scope and complexity
5. Call out risks and unknowns

Most PMs write specs in isolation, guessing about architecture. Engineers read the spec and point out gaps: "You didn't account for this dependency." "This won't work with our payment system." "We'd need to refactor X first."

Specs grounded in actual codebase data are more complete, more accurate, and faster to write.

The Spec Writing Problem

Traditional spec writing:

• PM writes a spec based on feature description, not codebase reality
• Engineers review and point out architectural conflicts (spec is half-wrong)
• Spec is revised, but technical details are still vague
• Implementation starts, and surprises emerge because the spec didn't account for technical constraints
• Schedule slips as engineers discover "Oh, we have to refactor this first"

The root cause: Specs aren't grounded in code.

How Glue Enables Code-Grounded Specs

Glue answers technical questions automatically:

Current state analysis: Instead of guessing "Does our API support bulk operations?", Glue shows:

• "API endpoint exists at /api/users/bulk-import"
• "Supports JSON payload, limit 1000 users per request"
• "Implemented in users-service/bulk-import.ts, uses queue-based processing"

Dependency mapping: Glue shows what your change touches:

• "This feature requires payment service integration" → Glue shows current payment integrations, protocols, rate limits
• "We'll need to update the user model" → Glue shows all code that touches the user model (high dependency = high blast radius = high risk)

Pattern documentation: Instead of writing "We'll follow REST conventions," Glue shows your actual patterns:

• "API error handling pattern is [shown from real code]"
• "Authentication flows through [specific middleware chain shown from code]"
• "Database migrations use [actual tool and pattern from codebase]"

Scope and risk quantification: Glue estimates:

• "This feature spans 8 services and 12 files. Complexity: high."
• "Requires refactoring payment module (legacy code). Risk: medium."
• "Similar feature took 4 weeks; this one is 50% larger, expect 6 weeks."

Spec Template With Glue

# Feature Spec: Bulk User Import

## Overview
[Brief feature description]

## Current State (from Glue)
- API endpoint: /api/users/bulk-import (users-service/bulk-import.ts, line 45)
- Limit: 1000 users per request
- Supported formats: JSON only
- Integration: Queued via bull (users-service/queue/jobs.ts)

## Proposed Change
[What we're adding]

## Affected Systems (Glue dependency analysis)
- users-service: HIGH (new endpoint variant)
- payment-service: MEDIUM (billing impact of bulk imports)
- notification-service: LOW (welcome emails)
- legacy-auth-module: HIGH (requires refactoring to support batch operations)

## Risks (Glue identified)
- Legacy auth module has low test coverage (32%). Recommend refactoring before implementation.
- Payment service has tight coupling to user creation. Bulk operations might exceed rate limits.

## Implementation Plan
1. Refactor legacy-auth-module (4 weeks)
2. Extend bulk-import endpoint (2 weeks)
3. Update payment integration (1 week)
4. Testing (1 week)

## Estimate: 8 weeks (includes refactoring risk buffer)

This spec is grounded in code. Architects read it and nod—it's accurate.

Real-World Impact

Before Glue: PM writes spec, engineers spend 3-4 hours reviewing and identifying gaps, spec is revised. Cycle repeats. Writing a spec takes 2 weeks.

After Glue: PM writes spec with Glue's analysis built in, engineers confirm/refine in 30 minutes. Spec is written in 3 days.

Time saved per feature: 9 days. Across 20 features per year = 180 hours = 9 weeks of PM time freed.

---

Frequently Asked Questions

Q: Does Glue write specs automatically? A: Not fully. Glue provides technical data (current state, dependencies, patterns, risks). PMs write the feature narrative and decisions. Glue + PM collaboration is faster and more accurate than either alone.

Q: What if our codebase changes between when Glue analyzes it and when we write the spec? A: Glue updates continuously as code changes. If the spec is written weeks later, revalidate the technical data—1-hour refresh usually surfaces any critical changes.

Q: How do we use Glue for specs on truly new features (no similar code exists)? A: Glue shows where similar patterns or integrations exist in your codebase. Even for new features, patterns (error handling, auth, data validation) are reused. Glue surfaces those precedents.