agentleFS
Sign inStart free
komlukkomluk/scaffolding/skills/spec-research/SKILL.md

spec-research

Skill16 starsChanged 5 days agoMITView on GitHub

Write OpenSpec proposal.md artifacts (why + what). TRIGGER when: capturing requirements, scope, and impact for a spec-driven feature. SKIP: technical design (use spec-design); external documentation research (use research-methodology).

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use kebab-case: user-auth, data-export, api-rate-limiting

    line 34
  2. Distinctive:

    Only list if spec-level REQUIREMENTS change (not just implementation)

    line 39
  3. Very specific:

    Check .scaffolding/openspec/specs/ for existing names

    line 40
  4. Distinctive:

    Leave empty if no requirement changes

    line 41

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

OpenSpec Proposal Writing

Guide for creating proposal.md -- the WHY document that anchors the entire workflow.

Output Path

Write to: {specs_path}/proposal.md

Path Enforcement: The specs_path MUST be .scaffolding/conversations/{UUID}/specs/ where {UUID} is a valid UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). NEVER use descriptive folder names.

.scaffolding/conversations/ is a symlink to <share>/projects/<repo-name>/conversations (paths below are unchanged; always go through the symlink).

Required Sections

SectionPurposeContent
WhyMotivation1-2 sentences. What problem? Why now?
What ChangesScopeBullet list. New capabilities, modifications, removals. Mark BREAKING
CapabilitiesContractNew + modified capabilities (kebab-case names)
ImpactBlast radiusAffected code, APIs, dependencies, systems
Agent AssignmentRoutingTable of agents, roles, artifacts
Rollback PlanSafetyRevert points, manual steps, affected systems

Capabilities Section (Critical)

This section creates the contract between proposal and design phases.

New Capabilities

  • Use kebab-case: user-auth, data-export, api-rate-limiting
  • Each becomes a requirement group in design.md
  • Brief description of what the capability covers

Modified Capabilities

  • Only list if spec-level REQUIREMENTS change (not just implementation)
  • Check .scaffolding/openspec/specs/ for existing names
  • Leave empty if no requirement changes

Quality Checklist

  • Goals are concrete and measurable (not vague)
  • Edge cases identified in Impact section
  • All affected agents listed in Agent Assignment
  • Rollback plan has specific revert steps
  • Capabilities use kebab-case naming
  • No implementation details (those go in design.md)
  • Stakeholder impact addressed

Template Structure

## Why

[1-2 sentences: problem + urgency]

## What Changes

- [Specific change 1]
- [Specific change 2]
- **BREAKING**: [Breaking change, if any]

## Capabilities

### New Capabilities
- `capability-name`: Brief description

### Modified Capabilities
- `existing-name`: What requirement is changing

## Impact

[Affected code, APIs, dependencies, systems]

## Agent Assignment

| Agent | Role | Artifacts |
|-------|------|-----------|
| architect | Analyst + Coordinator | proposal.md, design.md, tasks.md |
| researcher | External Research (if needed) | ResearchPack |
| developer | Developer | Source code |
| reviewer | Reviewer | Review report |

## Rollback Plan

- [ ] Identify revert points
- [ ] Document manual rollback steps
- [ ] List affected systems

Anti-Patterns

AvoidInstead
Vague goals ("improve performance")Measurable goals ("reduce p95 latency below 200ms")
Implementation detailsSave for design.md
Missing rollback planAlways include revert strategy
Skipping capabilities sectionThis is the design contract

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free