github / github/spec-kit

[Feature]: Prompt Style Guide

Open
#2,804 6 comments 0 reactions 0 assignees View on GitHub
enhancement feature-assess feature-needs-clarification
Dominant language
Python
Stars
137k
Forks
12.3k
Avg merge
2d 12h
Merged PRs (30d)
159

Description

### Problem Statement

I'm frustrated when I audit the core markdown prompt files and notice minor formatting, architectural, and structural consistency drift between sequential sections.

For example, in [templates/commands/specify.md (Lines 61-77)](https://github.com/github/spec-kit/blob/ed10b32014431a15c4e54e4ed7c92452230dd193/templates/commands/specify.md#L61-L77), Step 1 ("Generate a concise short name") uses clean dashes (`-`) to list out its sub-rules, but Step 2 ("Branch creation") drops bullet points entirely to use double-spaced paragraphs.

Additionally, within [templates/commands/specify.md (Lines 130-132)](https://github.com/github/spec-kit/blob/ed10b32014431a15c4e54e4ed7c92452230dd193/templates/commands/specify.md#L130-L132) under the Step 6 execution flow, section `v. Generate Functional Requirements` asks for "testable" requirements but does not explicitly mandate that they be "atomic."

Industry best practice for AI-driven software engineering shows that compound requirements can cause downstream logic fragmentation. While I haven't run into a broken output file myself, leaving these prompt discrepancies unaddressed introduces a strong hypothetical risk. An LLM might experience few-shot mimicry (structural anchoring), causing it to mirror the messy layouts or miss nested logic blocks entirely.

### Proposed Solution

I would like us to introduce a minimal Prompt Style Guide to establish baseline rules for any prompts added to this project (including core templates, community presets, and agent flows).

This guide will enforce:
1. Standardizing sub-step and constraint hierarchies using unified dashes (`-`).
2. Mandating explicit atomicity constraints for any prompt block generating requirements or tasks.
3. Prioritizing the active, imperative voice.

I plan to create this style guide by extracting the most common layout styles already present across the existing prompts. Any edge cases or styling ties during this baseline evaluation will be handled on a case-by-case basis.

### Alternatives Considered

I have considered several local and architectural workarounds, though none permanently solves the upstream problem for the community:
1. Using a local `.specify/memory/constitution.md` file to force these constraints at runtime.
2. Maintaining local template overrides inside individual project repositories.
3. Directly modifying the local `skill.md` files (which means effectively altering the underlying source code of Spec Kit).
4. Modifying agent-specific config files like `agents.md`.
5. Manually re-typing or editing the requirements into atomic, standard lines every single time the skill runs (highly inefficient).

### Component

Spec templates (BDD, Testing Strategy, etc.)

### AI Agent (if applicable)

None

### Use Cases

1. When community developers build new presets or commands, they have a clear guideline to prevent prompt quality from drifting.
2. During template maintenance, reviewers can instantly check incoming PRs against a set formatting baseline.
3. When AI agents run the workflows, consistent prompts help them follow the rules better and generate clean, atomic files.

### Acceptance Criteria

- [ ] A baseline Prompt Style Guide markdown file is added to the documentation.
- [ ] Existing prompt templates are lightly refactored to align with the new layout standard.

### Additional Context

I noticed these template consistency errors while auditing my local project setup.

*AI Disclosure: I used an AI assistant to help me write, refine, and format this entire issue template.*

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.