---

name: authoring-roadmap description: This skill should be used when the user asks to "create roadmap", "generate gap analysis", "identify improvement priorities", or mentions "roadmap", "gap analysis", "evolution plan", "improvement priorities", or "brownfield gaps". Produces prioritized gap cards with dependencies for incremental codebase improvement.

Authoring Evolution Roadmap

Purpose

Create evolution roadmaps that identify gaps between current codebase state and constitution requirements. Produces prioritized gap cards with dependencies, enabling incremental improvement without overwhelming teams.

When to Use

• After brownfield codebase analysis is complete
• After constitution is created for a brownfield project
• When identifying what needs to change to meet constitution requirements
• When planning incremental codebase improvements

Input Requirements

To create an evolution roadmap, you need:

1. Codebase Analysis (.humaninloop/memory/codebase-analysis.md)

   • Essential Floor Status table
   • Inventory of existing patterns
   • Identified inconsistencies

2. Constitution (.humaninloop/memory/constitution.md)

   • Principles with requirements
   • Quality gates with thresholds
   • Technology stack requirements

Gap Identification Process

Step 1: Essential Floor Gaps

For each Essential Floor category, check status from codebase analysis:

Example:

CopyCodebase Analysis shows:
- Security: partial (has auth, missing input validation)
- Testing: partial (has tests, coverage at 45%)
- Error Handling: present
- Observability: absent

Gaps to create:
- GAP-001: Implement input validation (Security)
- GAP-002: Increase test coverage to 80% (Testing)
- GAP-003: Implement structured logging (Observability)
- GAP-004: Add correlation IDs (Observability)

Step 2: Constitution Compliance Gaps

For each constitution principle, check if codebase complies:

1. Read principle requirements (MUST, SHOULD statements)
2. Compare against codebase analysis findings
3. Create gap if requirement not met

Example:

CopyConstitution Principle: "API responses MUST include correlation IDs"
Codebase Analysis: "Correlation IDs: absent"
→ Create GAP-005: Add correlation IDs to API responses

Step 3: Prioritize Gaps

Assign priority based on:

Step 4: Identify Dependencies

Determine which gaps block or enable others:

• Blocks: What this gap prevents if not addressed
• Enables: What fixing this gap unlocks
• Depends On: Other gaps that must be addressed first

Gap Card Format

Each gap uses the hybrid format (structured header + prose body):

Copy### GAP-XXX: [Title]

| Aspect | Value |
|--------|-------|
| Priority | P1/P2/P3 |
| Category | Security/Testing/ErrorHandling/Observability/Other |
| Blocks | [What this prevents] |
| Enables | [What fixing unlocks] |
| Depends On | GAP-YYY, GAP-ZZZ (or "None") |
| Effort | Small/Medium/Large |

**Current state**: [Factual description from codebase-analysis.md]

**Target state**: [What constitution requires]

**Suggested approach**: [Actionable guidance for addressing]

**Related files**:
- `path/to/relevant/file.ts`
- `path/to/another/file.py`

Roadmap Structure

Copy# Evolution Roadmap

> Generated: [ISO timestamp]
> Based on: codebase-analysis.md, constitution.md
> Status: active

---

## Overview

[1-2 sentence summary of gap analysis findings]

**Total Gaps**: N
- P1 (Critical): X
- P2 (Important): Y
- P3 (Nice-to-have): Z

---

## Gap Summary

| ID | Title | Priority | Category | Depends On | Effort |
|----|-------|----------|----------|------------|--------|
| GAP-001 | [title] | P1 | Security | None | Medium |
| GAP-002 | [title] | P2 | Testing | GAP-001 | Large |
| ... | ... | ... | ... | ... | ... |

---

## Dependency Graph

[Foundation] └── GAP-001: [title] └── GAP-002: [title] └── GAP-005: [title]

[Parallel Track] └── GAP-003: [title] └── GAP-004: [title]

Copy
---

## Gap Cards

[Individual gap cards in priority order]

---

## Maintenance Protocol

[Standard maintenance instructions]

Priority Definitions

Effort Estimates

Dependency Graph Rules

1. Security gaps come first - They often block other improvements
2. Foundation before features - Infrastructure gaps enable feature gaps
3. Minimize chains - Long dependency chains increase risk
4. Identify parallel tracks - Gaps that can be addressed independently

Quality Checklist

Before finalizing roadmap:

• Every Essential Floor gap identified (partial/absent → gap)
• Every constitution MUST violation has a gap
• All gaps have Priority assigned (P1/P2/P3)
• All gaps have Category assigned
• All gaps have Effort estimate
• Dependencies identified and documented
• Dependency graph shows clear execution order
• No circular dependencies
• Current state references codebase-analysis.md
• Target state references constitution requirements

Anti-Patterns

Integration with Later Phases

When agents in /plan, /tasks, /implement address roadmap gaps:

1. Note in commits: Include "Addressed: GAP-XXX"
2. Suggest new gaps: If discovering issues not in roadmap, note "Suggested gap: [description]"
3. Supervisor decides: Human reviews and approves roadmap updates

Agents should read .humaninloop/memory/evolution-roadmap.md to:

• Understand existing improvement priorities
• Avoid creating work that conflicts with roadmap
• Note when their work addresses a gap