[Feature]: Prompt Style Guide

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), 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) 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:

Standardizing sub-step and constraint hierarchies using unified dashes (-).
Mandating explicit atomicity constraints for any prompt block generating requirements or tasks.
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:

Using a local .specify/memory/constitution.md file to force these constraints at runtime.
Maintaining local template overrides inside individual project repositories.
Directly modifying the local skill.md files (which means effectively altering the underlying source code of Spec Kit).
Modifying agent-specific config files like agents.md.
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

When community developers build new presets or commands, they have a clear guideline to prevent prompt quality from drifting.
During template maintenance, reviewers can instantly check incoming PRs against a set formatting baseline.
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.

Hi maintainers — I’d like to work on this as a focused contribution. My proposed scope is:

Add a concise prompt style guide documenting the existing conventions (hierarchy, imperative voice, and atomic requirements).
Make only the minimal consistency edits to the examples identified in this issue, avoiding broad template rewrites.
Add/update documentation references and validate the affected prompt files.

I’ll wait for maintainer approval and assignment before implementing, as requested by the contribution guidelines. I used ChatGPT to review the repository guidance and draft this proposal.

Would this focused scope be acceptable?

@benderdragon

Feature assessment — prompt-style-guide · Stage 1/5: Intake

Idea Intake: Prompt Style Guide

Slug: prompt-style-guide
Created: 2026-08-19
Source: GitHub issue [Feature]: Prompt Style Guide #2804 — [Feature]: Prompt Style Guide #2804 (host: github.com, policy: allowlisted)
Type: improvement

Idea (as captured)

The requester (@benderdragon) observed minor formatting and structural consistency drift in core markdown prompt templates, specifically in templates/commands/specify.md. Two concrete examples are cited:

Step 1 ("Generate a concise short name") uses dashes (-) for sub-rules, while Step 2 ("Branch creation") uses double-spaced paragraphs without bullet points.

Step 6, section v. Generate Functional Requirements, asks for "testable" requirements but does not explicitly mandate that they be "atomic."

The requester proposes introducing a minimal Prompt Style Guide document to establish baseline formatting rules for all prompts in the project (core templates, community presets, agent flows), plus lightly refactoring existing templates to align with the guide.

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

Restated

The proposal is to add a new Prompt Style Guide document defining baseline formatting conventions (bullet hierarchy, imperative voice, atomicity for requirement blocks) for Spec Kit's prompt/command templates, along with minimal consistency edits to existing templates to match those conventions.

Origin & Context

Raised by: @benderdragon (community contributor, no prior association with the project)
Trigger: Author noticed formatting inconsistencies while auditing their local Spec Kit setup
Issue date: 2026-06-02
Comment: @Yash-Chindam expressed interest in contributing a focused implementation (2026-08-18); also AI-assisted

First-Glance Unknowns

[NEEDS CLARIFICATION: How widespread is the formatting drift across all templates — is it limited to the two specific locations cited, or are there many instances?]
[NEEDS CLARIFICATION: Have these inconsistencies caused any actual problems (wrong agent output, missed logic) — or is the LLM mimicry risk purely hypothetical?]
[NEEDS CLARIFICATION: Who would own maintaining a Prompt Style Guide long-term, and would it be enforced (e.g., via lint/CI) or only advisory?]
[NEEDS CLARIFICATION: Do maintainers want a formal style guide, or do they prefer to handle consistency via template review in PRs?]
[NEEDS CLARIFICATION: Is the "atomicity" requirement change for functional requirements in scope for this issue, or is that a separate improvement?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #2804 · 451 AIC · ⌖ 22.5 AIC · ⊞ 36.4K · ◷

@benderdragon

Feature assessment — prompt-style-guide · Stage 2/5: Research

Idea Research: Prompt Style Guide

Slug: prompt-style-guide
Created: 2026-08-19
Evidence confidence (overall): medium

Users & Demand

Community contributor (issue author, @benderdragon) raised this after auditing their local Spec Kit setup. The issue has 0 reactions and 1 comment (another community member offering to contribute). There is no evidence of broader community demand or maintainer endorsement. — [source: GitHub issue [Feature]: Prompt Style Guide #2804] (confidence: high, cited)
One follow-on volunteer (@Yash-Chindam) expressed interest in a focused implementation (add style guide + minimal edits), also noting AI assistance. This is a single data point, not a demand signal. — [source: GitHub issue [Feature]: Prompt Style Guide #2804 comment] (confidence: high, cited)
No support tickets, forum posts, or maintainer statements referencing template formatting inconsistency as a pain point were found in accessible repository artifacts. — [source: codebase inspection] (confidence: medium, cited)

Prior Art

CONTRIBUTING.md exists and references the templates directory for review and testing, but contains no formatting conventions or style rules for prompt/command templates. It does note that "large changes that materially impact the work of the CLI ... need prior maintainer discussion." — [source: CONTRIBUTING.md, codebase] (confidence: high, cited)
No existing Prompt Style Guide or equivalent formatting rules document was found anywhere in the repository (docs/, templates/, CONTRIBUTING.md, README.md). — [source: codebase inspection] (confidence: high, cited)
The assess extension commands (.specify/extensions/assess/commands/*.md) use a consistent style internally (dash-based sub-bullets, imperative voice throughout, no mixed prose/bullet patterns). This was introduced after the core templates and appears more disciplined. — [source: codebase inspection] (confidence: high, cited)
The core command templates (templates/commands/*.md) do exhibit the mixing pattern described in the issue: numbered steps use dashes for sub-items (e.g., Step 1 of specify.md) but some numbered steps (e.g., Step 2 "Branch creation" in specify.md) use prose paragraphs without bullets. This pattern appears in checklist.md, clarify.md, converge.md, plan.md, and specify.md. — [source: codebase inspection, grep analysis] (confidence: high, cited)
The "atomic requirements" claim in the issue is accurate as a gap: specify.md Step 6-v says "Each requirement must be testable" but does not say "atomic." Whether "atomic" is implied by "testable" or genuinely missing is a judgment call. — [source: templates/commands/specify.md] (confidence: high, cited)

Market & Context

Users who contribute new commands or presets today have no formatting reference beyond reading existing templates. If existing templates are themselves inconsistent, there is no clear "correct" pattern to follow. — [source: codebase inspection] (confidence: medium, cited)
The cost of doing nothing is low: the inconsistencies cited are cosmetic/structural and have not been reported to cause wrong agent outputs. — [ASSUMPTION, no bug reports found] (confidence: medium, assumption)

Data & Constraints

Scope of inconsistency: All 10 core command templates use dash-based bullets for sub-items in most numbered steps. 5 templates mix in prose paragraphs for some steps. This is a minor, bounded issue — not a pervasive formatting collapse. — [source: codebase grep analysis] (confidence: high, cited)
No lint or CI enforcement for template formatting currently exists. A style guide without enforcement tooling is advisory only. — [source: codebase inspection] (confidence: high, cited)
CONTRIBUTING.md explicitly requires maintainer agreement for "large changes that materially impact the work of the CLI." A style guide + template refactoring PR would likely cross this threshold and require prior discussion. — [source: CONTRIBUTING.md] (confidence: high, cited)

Evidence Against the Idea

The LLM mimicry risk is speculative. The issue states no actual wrong outputs have been produced; the risk is described as "hypothetical." LLMs are generally robust to minor stylistic variation in instruction blocks — the claim that inconsistent bullets cause "structural anchoring" or "missed nested logic" is unsubstantiated. — [ASSUMPTION, no empirical data cited by requester] (confidence: medium)
Low community signal. Zero reactions on the issue, no maintainer engagement, no reports of practical harm from the formatting drift. — [source: GitHub issue [Feature]: Prompt Style Guide #2804] (confidence: high, cited)
Maintenance overhead. Without CI tooling, a style guide will likely drift from reality as templates evolve, adding a document that becomes a liability rather than an asset. — [ASSUMPTION] (confidence: medium)
The refactoring acceptance criterion ("existing prompt templates are lightly refactored") is underspecified — any template edit risks regressions in agent behavior that require manual testing per CONTRIBUTING.md. — [source: CONTRIBUTING.md] (confidence: high, cited)

Gaps & Open Questions

[NEEDS CLARIFICATION: Have maintainers observed agent output quality problems attributable to template formatting inconsistency?]
[NEEDS CLARIFICATION: Is there appetite for a style guide that is enforced (lint/CI) vs. advisory only?]
[NEEDS CLARIFICATION: Would maintainers consider the "atomicity" requirement addition in scope for this issue?]

Sources

[Feature]: Prompt Style Guide #2804 (host: github.com, policy: allowlisted)
Codebase: templates/commands/*.md, CONTRIBUTING.md, .specify/extensions/assess/commands/*.md (local file reads)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #2804 · 451 AIC · ⌖ 22.5 AIC · ⊞ 36.4K · ◷

Feature assessment — prompt-style-guide · Stage 3/5: Problem

Problem Definition: Prompt Style Guide

Slug: prompt-style-guide
Created: 2026-08-19
Inputs used: intake.md | research.md

Problem Statement

Core Spec Kit command templates have minor, inconsistent formatting (mixed bullet-versus-prose sub-steps) with no documented baseline convention to guide contributors, making it unclear which pattern is "correct" when writing new templates or reviewing PRs. The practical impact is low — no agent output failures have been reported — but the absence of any formatting reference creates a low-grade consistency problem that could accumulate over time.

Affected Users & Stakeholders

Users: Community contributors writing new commands, presets, or extensions — they have no formatting reference and may follow inconsistent patterns from existing templates.
Users: Project maintainers reviewing template PRs — they lack a documented standard to cite in reviews.
Stakeholders: Project maintainers (github/spec-kit team) — they decide whether a style guide is worth creating and maintaining.
Stakeholders: End users running Spec Kit commands — minimally affected, as no output quality issues from the formatting drift have been reported.

Goals

Establish a documented baseline formatting convention for Spec Kit command templates so contributors and reviewers have a shared reference.
Eliminate the specific formatting inconsistencies identified in templates/commands/specify.md (bullet/prose mixing in numbered steps).

Non-Goals

Broad rewrites of all template content (only structural/formatting normalization).
Enforcement tooling (CI lint) — out of scope for the initial guide; advisory only unless explicitly added later.
Changing the semantics or behavior of existing agent commands (style normalization only).
Mandating the "atomicity" requirement wording in specify.md without separate maintainer validation.

Success Metrics

A Prompt Style Guide document exists and is findable in the repository (qualitative; baseline: none today).
The specific formatting inconsistencies cited in issue [Feature]: Prompt Style Guide #2804 are resolved in specify.md (baseline: 2 identified locations with mixed formatting).
New template PRs can be reviewed against the style guide within one review cycle without ambiguity (qualitative; [NEEDS CLARIFICATION: maintainers to confirm]).

Cost of Inaction

Without a style guide, formatting inconsistencies will accumulate as more contributors add templates and presets. The drift is cosmetic today but makes the template corpus harder to maintain and review over time. However, the near-term cost of inaction is low — no agent output problems have been traced to formatting inconsistency.

Open Questions

[NEEDS CLARIFICATION: Do maintainers want an advisory style guide, an enforced one (with lint/CI), or neither?]
[NEEDS CLARIFICATION: Is the "atomic requirements" addition to specify.md in scope here, or a separate proposal?]
[NEEDS CLARIFICATION: Should the style guide cover only core templates, or also extension commands and community presets?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #2804 · 451 AIC · ⌖ 22.5 AIC · ⊞ 36.4K · ◷

Feature assessment — prompt-style-guide · Stage 4/5: Concept

Concept: Prompt Style Guide

Slug: prompt-style-guide
Created: 2026-08-19
Recommended option: B — Minimal advisory style guide + targeted fixes

Options

Option A — Full Style Guide with Template Refactor

Sketch: Create a comprehensive Prompt Style Guide document under docs/ covering all formatting rules (bullet hierarchy, voice, atomicity, frontmatter conventions), then refactor all 10+ core command templates to conform. Community presets and extension commands also in scope.
Appetite: medium (weeks)
Trade-offs: Wins — consistent corpus; a reference future contributors can follow. Sacrifices — significant template editing risk (each touched template requires manual agent testing per CONTRIBUTING.md), high review burden, large PR that maintainers require prior agreement for.
Rabbit holes: Defining rules that templates already silently violate intentionally (e.g., prose-style steps may be deliberate for readability); testing all changed templates against live agents; scope creep into semantic changes.

Option B — Minimal Advisory Style Guide + Targeted Fixes

Sketch: Add a short, focused style guide (docs/guides/prompt-style-guide.md or similar) documenting the observed dominant conventions (dash-based sub-bullets, imperative voice, numbered steps for major phases), then make only the specific formatting fixes cited in the issue — normalizing the two locations in specify.md that mix prose with bullets. No broad refactor. Advisory only.
Appetite: small (days)
Trade-offs: Wins — low-risk, scoped, gives contributors a reference without requiring large coordinated review. Sacrifices — leaves formatting drift in other templates; advisory guide may not be maintained. Risks — even narrow specify.md edits require manual testing of the specify command.
Rabbit holes: Deciding what counts as "canonical" formatting when templates intentionally vary; the "atomicity" addition to specify.md needs separate validation.

Option C — No Style Guide; PR-level Convention Only

Sketch: Document in CONTRIBUTING.md that template formatting is reviewed ad hoc; contributors should mirror the nearest existing template. Fix the specific specify.md inconsistencies via a small PR with no separate guide document.
Appetite: small (hours)
Trade-offs: Wins — minimal overhead; no new document to maintain. Sacrifices — contributors still have no clear reference; same problem recurs.
Rabbit holes: None significant.

Recommendation

Option B — a minimal advisory style guide plus the two targeted fixes in specify.md. This delivers the core value (a formatting reference for contributors and reviewers) at low risk and low maintenance cost.

Prerequisite: Maintainer confirmation that a style guide is wanted. CONTRIBUTING.md requires prior agreement for template-touching changes. A PR should be preceded by a short maintainer discussion in this issue.

The "atomicity" wording change to specify.md should be handled separately — not bundled here — because it could alter agent output behavior and requires dedicated testing.

Out of Scope (for the recommended option)

Refactoring templates other than the two specific locations in specify.md cited in the issue.
CI/lint enforcement of the style guide.
Changing "testable" → "testable and atomic" in specify.md without separate maintainer sign-off.
Community presets and extension commands (guide references them but does not mandate immediate refactoring).

Assumptions to Validate

Maintainers want a Prompt Style Guide document (not confirmed — zero maintainer engagement on issue [Feature]: Prompt Style Guide #2804 to date).
The two cited formatting locations in specify.md can be normalized without changing agent behavior (formatting-only change, no semantic impact).
A docs/guides/ location is an appropriate home for the guide (matches existing docs/guides/ structure).

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #2804 · 451 AIC · ⌖ 22.5 AIC · ⊞ 36.4K · ◷

Feature assessment — prompt-style-guide · Stage 5/5: Decision — verdict needs-clarification

Decision: Prompt Style Guide

Slug: prompt-style-guide
Decided: 2026-08-19
Verdict: needs-clarification
Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	adequate	The formatting inconsistency in core templates is real and documented with specific file locations. The absence of a contributor style guide is a genuine gap. However, no agent output failures have been traced to this drift — the problem is cosmetic/maintenance-level, not functional.
Evidence strength	weak	The key risk claim (LLM few-shot mimicry from inconsistent bullets) is explicitly labeled as hypothetical by the requester and is unsupported by any data. Community demand signal is minimal (0 reactions, 1 AI-assisted volunteer comment). No maintainer has confirmed this is a priority.
Value vs. inaction	adequate	A style guide delivers real value as a contributor reference and reduces future drift. However, the near-term cost of inaction is very low — no known harm today. Value is mostly preventive.
Feasibility / appetite	strong	Option B (minimal guide + targeted fixes) is well-scoped and achievable in days. The technical work is straightforward; the constraint is process — maintainer agreement is required per CONTRIBUTING.md before implementation.
Strategic fit	unknown	No maintainer has weighed in on whether a Prompt Style Guide aligns with current project priorities. CONTRIBUTING.md requires prior agreement for template-touching changes. Strategic fit cannot be assessed without maintainer input.
Risk posture	adequate	Option B is low-risk technically. The main risk is scope creep into semantic template changes (e.g., the "atomicity" addition), which is explicitly excluded from the recommendation. Process risk (proceeding without maintainer agreement) is the primary concern.

Verdict & Rationale

needs-clarification. The problem is real and the concept is sound, but the evidence strength is rated weak — the central risk claim (LLM mimicry from inconsistent formatting) is speculative, community demand is minimal, and no maintainer has confirmed interest. Per the pipeline rules, a go requires evidence strength of adequate or better; weak evidence mandates needs-clarification.

Additionally, there is a blocking process question: CONTRIBUTING.md explicitly requires maintainer agreement before large or template-touching changes. No maintainer has commented on issue #2804 in the two months since it was filed (2026-06-02 → 2026-08-19). Before any implementation proceeds, maintainers should confirm they want a Prompt Style Guide and agree on its scope.

The concept (Option B) is viable and well-shaped. If maintainers confirm interest, this could move to go quickly.

If needs-clarification

Blocking questions:
- [NEEDS CLARIFICATION: Have maintainers observed agent output quality problems attributable to template formatting inconsistency? (Validates the core risk claim.)]
- [NEEDS CLARIFICATION: Do maintainers want a Prompt Style Guide? If yes, advisory or enforced (CI/lint)?]
- [NEEDS CLARIFICATION: Is the scope of Option B (guide + targeted specify.md fixes only) acceptable, or should it be broader or narrower?]
- [NEEDS CLARIFICATION: Should the "atomicity" requirement addition to specify.md be in scope here or tracked separately?]
Revisit stage: research (gather maintainer signal) → then decide again

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #2804 · 451 AIC · ⌖ 22.5 AIC · ⊞ 36.4K · ◷

[Feature]: Prompt Style Guide #2804

Description

Problem Statement

Proposed Solution

Alternatives Considered

Component

AI Agent (if applicable)

Use Cases

Acceptance Criteria

Additional Context

Activity

Yash-Chindam commented on Aug 18, 2026

github-actions commented on Aug 19, 2026

Idea Intake: Prompt Style Guide

Idea (as captured)

Restated

Origin & Context

First-Glance Unknowns

github-actions commented on Aug 19, 2026

Idea Research: Prompt Style Guide

Users & Demand

Prior Art

Market & Context

Data & Constraints

Evidence Against the Idea

Gaps & Open Questions

Sources

github-actions commented on Aug 19, 2026

Problem Definition: Prompt Style Guide

Problem Statement

Affected Users & Stakeholders

Goals

Non-Goals

Success Metrics

Cost of Inaction

Open Questions

github-actions commented on Aug 19, 2026

Concept: Prompt Style Guide

Options

Option A — Full Style Guide with Template Refactor

Option B — Minimal Advisory Style Guide + Targeted Fixes

Option C — No Style Guide; PR-level Convention Only

Recommendation

Out of Scope (for the recommended option)

Assumptions to Validate

github-actions commented on Aug 19, 2026

Decision: Prompt Style Guide

Scorecard

Verdict & Rationale

If needs-clarification

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions