Specs generated by /specify are hard to read for non-technical reviewers (BAs/QA) — is this a common experience?

[AbgaryanNver]

We're adopting spec-kit in our SDLC across multiple projects, and I'd like to hear how others handle the readability of generated specs.

Our workflow: Business Analysts create specs with the /specify command, and the spec becomes the source of truth in Jira — replacing the traditional Jira requirement. Both the BA and QA then review the spec before development starts.

The problem: Our BAs report that the specs generated by /specify are hard to read and not human-friendly. The structure works well for feeding into /plan and implementation, but as a document that non-technical stakeholders review and sign off on, it feels awkward — , too rigid/template-driven in others.

Questions for the community:

1. Has anyone else run into this when using specs as review artifacts for BAs/QA rather than just as AI input?
2. Have you customized the spec template ort more readable for humans? If so, how?
3. Is improving human readability of /specify output on the roadmap, or is the spec intentionally optimized for agent consumption rather than human review?

Any experience or workarounds would be much appreciated. Thanks!

[mnriem]

Thanks for raising this — it's a common experience, and it comes from a deliberate design choice rather than a gap.

Why the spec reads the way it does: /specify output is optimized first and foremost for agent consumption. spec.md is the machine-readable source of truth that feeds /plan, /tasks, and /implement. Making the template more prose-friendly for human sign-off would trade away the structure that downstream automation depends on. So rather than reshape the spec, a pattern worth considering is: keep spec.md as the SSOT, and generate a derived, human-readable review artifact from it for BA/QA sign-off.

The community catalog has extensions built around this idea (these are community-maintained, not first-party — evaluate them for your own context):

• product — generates a PRFAQ, Lean PRD, and stakeholder summaries from an engineering spec.
• tldr — renders spec.md/plan.md into a review-oriented HTML dashboard + PR-native Markdown that surfaces risks.
• preview — low/mid/high-fidelity previews of spec artifacts as Markdown or self-contained HTML.
• ears — rewrites requirements into EARS (unambiguous, testable sentence patterns), which tends to help QA readability specifically.
• spec-validate / critique — comprehension checks, review gating, and an approval state before /implement, which maps to a "BA and QA both sign off before development" gate.
• jira / jira-sync — since your spec becomes the Jira requirement, these mirror specs into Jira Epics/Stories/Subtasks so the readable artifact lives where your reviewers already work.

Any of the projection-style ones (product, tldr, preview) address the core readability ask; the others cover adjacent needs (testable requirements, sign-off gating, Jira sync) depending on where your review actually happens.

One reframing worth considering: if what your BAs actually need to review is "is this the right problem, what's the appetite, go / no-go" rather than the detailed functional spec, that review belongs upstream of /specify. The first-party assess extension is a pre-SDD discovery funnel whose artifacts (problem.md, concept.md, decision.md) are deliberately role-neutral and human-friendly — a BA can read and sign off on those directly, and only go ideas hand off to /specify. It won't make spec.md itself more readable, but it may be the better home for the non-technical review you're describing.

Short version: /specify output being agent-shaped is intentional. The fix is a human-readable projection on top of the spec, or moving the non-technical sign-off upstream into assess — rather than loosening the spec template itself.

---

Posted by GitHub Copilot (model: Claude Opus 4.8) on behalf of @mnriem.