How to Handle Feedback in GitHub Spec Kit Before and After Implementation

TL;DR

• GitHub Spec Kit is useful for investigation because it turns a vague idea into a sequence of reviewable artifacts: spec.md, plan.md, tasks.md, and related checks.
• The best time to handle most feedback is before implementation, while comments can still change requirements, architecture, and task order cheaply.
• Pre-implementation feedback should be routed by artifact:
  • product intent and user behavior go to spec.md
  • architecture and constraints go to plan.md
  • sequencing and ownership go to tasks.md
• Post-implementation feedback should be triaged as:
  • implementation defect
  • missed requirement
  • changed requirement
  • documentation drift
  • new feature request
• The most important team decision is your spec persistence model:
  • flow-back spec
  • flow-forward spec
  • living spec
• My default recommendation for teams with many comments is:
  • use flow-forward for major requirement changes
  • use flow-back for implementation discoveries inside the same PR
  • use a living spec only when the team is ready to maintain spec.md as the product contract
• Spec Kit is not your only option. Depending on the problem, you may prefer Kiro, Tessl, BDD/Gherkin, contract-first API development, or a lighter RFC plus issue workflow.

What You Will Learn Here

• What GitHub Spec Kit is useful for during investigation
• How to use Spec Kit to look for alternatives before locking in a plan
• How to triage many comments on spec.md, plan.md, and tasks.md
• How to handle feedback before implementation starts
• How to handle feedback after implementation has already happened
• How to choose between flow-back, flow-forward, and living specs
• When an alternative to Spec Kit may be a better fit

The Research Question

The scenario is very real:

You created Spec Kit artifacts for a feature. Before implementation, PMs, engineers, designers, QA, security, and maybe a customer-facing team left many comments. Then implementation started. After that, even more feedback arrived on the code, the behavior, the test coverage, and the spec artifacts.

Now what?

The naive answer is:

Just update the docs and code until everyone is happy.

That sounds reasonable, but it usually creates drift.

The better answer is:

Treat every comment as an input to the artifact lifecycle.
Route it to the right phase.
Update the smallest source of truth that can resolve it.
Re-run the relevant Spec Kit gate before moving forward.

That is the operating model this article builds.

What GitHub Spec Kit Actually Gives You

GitHub describes Spec Kit as a toolkit for Spec-Driven Development, where specifications become active delivery artifacts instead of documents that get written once and forgotten.

The current docs describe the core flow as:

Spec -> Plan -> Tasks -> Implement

For production work, the quick start recommends a fuller path:

/speckit.constitution
  -> /speckit.specify
  -> /speckit.clarify
  -> /speckit.checklist
  -> /speckit.plan
  -> /speckit.tasks
  -> /speckit.analyze
  -> /speckit.implement

That sequence matters because feedback belongs in different places depending on when it arrives.

Before implementation, feedback is cheap because it can still reshape the spec, plan, and task list.

After implementation, feedback is more expensive because it may require code changes, test changes, artifact reconciliation, or a new feature directory.

How to Use Spec Kit for Investigation

Spec Kit is not only a build workflow. Used carefully, it is also an investigation workflow.

The trick is to stop treating investigation as a giant prompt like:

Research this feature and tell me what to build.

Use the phases instead.

question
  -> product intent
  -> open ambiguities
  -> technical options
  -> task shape
  -> consistency check

In practice:

1. Use /speckit.specify to state the problem and the user outcome.
2. Use /speckit.clarify to expose missing product decisions.
3. Use /speckit.plan to compare technical approaches.
4. Use /speckit.tasks to see what each approach would cost.
5. Use /speckit.analyze to catch contradictions before code begins.

Here is a prompt style I would use for investigation:

/speckit.plan
Investigate three implementation alternatives before choosing one:

1. Minimal change inside the existing module
2. New internal service boundary
3. Third-party managed service integration

For each option, include:
- product tradeoffs
- engineering complexity
- migration risk
- operational risk
- testing impact
- expected rollback strategy

Do not choose an option until the tradeoff table is complete.

This is useful for engineers and PMs because the conversation moves from “what do you think?” to “which tradeoff are we accepting?”

Where Feedback Should Go

When many comments arrive, do not process them in chronological order.

Process them by destination.

comment
  |
  +-- changes user behavior? -------> spec.md
  |
  +-- changes constraints/design? ---> plan.md
  |
  +-- changes work order/scope? ----> tasks.md
  |
  +-- exposes contradiction? -------> analyze/checklist
  |
  +-- finds code mismatch? ---------> implementation + tests
  |
  +-- asks for new capability? -----> new spec or linked follow-up

That routing is the first discipline. Without it, every artifact slowly becomes a mixed pile of product intent, technical decisions, random tasks, and bug notes.

A Feedback Triage Table

I like using a small table during review:

This sounds basic. In practice, it is the difference between review chaos and a usable decision log.

The Ideal Pre-Implementation Feedback Workflow

Before implementation, the goal is to make comments cheap.

I would run feedback like this:

draft spec
  -> collect comments
  -> route comments
  -> resolve product ambiguity
  -> update spec
  -> validate checklist
  -> draft plan
  -> collect engineering/security/QA comments
  -> update plan
  -> generate tasks
  -> run analyze
  -> implementation starts

Step 1: Freeze the review surface briefly

Do not let the artifact set change every five minutes while reviewers are reading it.

Create a review snapshot:

specs/042-billing-export/
  spec.md
  plan.md
  tasks.md
  research.md

Then ask reviewers to comment against that snapshot.

Step 2: Separate “must resolve now” from “can become follow-up”

Use a simple label set:

blocker: must resolve before implementation
clarify: answer before plan/tasks are final
plan-change: affects architecture or constraints
task-change: affects sequencing or ownership
follow-up: valid, but not part of this slice
out-of-scope: intentionally excluded

This prevents the review from becoming a referendum on the entire product roadmap.

Step 3: Run /speckit.clarify for requirement comments

If comments reveal missing product decisions, do not jump to the technical plan.

Use a clarification pass:

/speckit.clarify
Review the open comments tagged clarify and blocker.

For each comment:
- identify the missing decision
- propose 2-3 possible answers
- recommend the lowest-risk answer
- update spec.md only after the decision is explicit

This keeps PM feedback in the product layer before engineers overfit the design.

Step 4: Run /speckit.checklist before planning

The official quick start recommends /speckit.checklist before creating the technical plan. That is exactly where I would put it after a heavy comment round.

The checklist is the “are we ready to design?” gate.

If it fails, that is good news. You found the expensive confusion early.

Step 5: Use /speckit.plan for alternatives

When engineers disagree, force the disagreement into an options table.

/speckit.plan
Based on the reviewed spec, compare these approaches:

A. Extend the current export worker
B. Add a dedicated export orchestration module
C. Use the existing workflow engine

For each approach, include:
- files or modules likely affected
- migration plan
- testing strategy
- operational risk
- reason to reject or accept

Select one recommendation and explain why.

This is the point where Spec Kit becomes useful for investigation, not just documentation.

Step 6: Run /speckit.analyze before implementation

The quick start recommends /speckit.analyze before /speckit.implement so contradictions are caught while tasks can still be adjusted.

After a large comment round, this is not optional in my workflow.

I would ask it to check:

/speckit.analyze
Audit spec.md, plan.md, and tasks.md after the review updates.

Flag:
- requirement not represented in the plan
- plan decision not represented in tasks
- task with no requirement or plan source
- contradiction between acceptance criteria and implementation plan
- missing test task for a high-risk behavior

Only then should implementation start.

The Ideal Post-Implementation Feedback Workflow

After implementation, the question changes.

Before code exists, the comment says:

What should we build?

After code exists, the comment may mean:

The code failed the spec.
The spec missed reality.
The requirement changed.
The plan was wrong.
The artifact set drifted.

Those are very different problems.

Here is the post-implementation flow I recommend:

review comment
  -> classify
  -> choose artifact owner
  -> update code or spec source
  -> update tests
  -> reconcile derived artifacts
  -> re-run checks
  -> decide merge or follow-up

Step 1: Classify the comment

Use this decision tree:

Does the implementation violate the approved spec?
  yes -> fix code and tests
  no
    |
    +-- Did the spec miss a real requirement?
    |     yes -> update spec, then plan/tasks/tests
    |
    +-- Did the requirement change after approval?
    |     yes -> decide flow-back vs flow-forward vs living spec
    |
    +-- Is this a new capability?
          yes -> create follow-up spec

This is where many teams accidentally get into trouble. They handle every post-implementation comment as a code review comment, even when it is actually a spec change.

Step 2: Choose the right persistence model

The current Spec Kit docs explicitly say the toolkit does not force one maintenance strategy for spec.md, plan.md, and tasks.md after requirements change.

The docs describe three common models:

My practical recommendation:

• Use flow-back for discoveries inside the same implementation PR.
• Use flow-forward when the feedback changes the approved product scope.
• Use living spec only when the team has agreed that spec.md is the long-term contract.

Step 3: Do not bury new requirements in code review

If the implementation is correct but the stakeholder wants new behavior, create a new delta.

Example:

specs/
  042-billing-export/
    spec.md
    plan.md
    tasks.md
  043-scheduled-billing-export/
    spec.md
    plan.md
    tasks.md

Then link the lineage:

## Relationship to Previous Work

This spec extends `042-billing-export`.

It does not replace the manual export flow.
It adds scheduled export configuration, execution, and audit behavior.

That keeps the current PR shippable and the new request visible.

Step 4: Reconcile tests with the artifact that won

If the spec wins, code and tests change.

If the implementation discovery wins, update the spec and tests so future readers understand why.

If the new requirement is deferred, add a follow-up spec or issue and keep the current tests aligned with the current approved behavior.

This is the boring part. It is also the part that protects the team from “the docs say one thing, the tests say another, and production does a third thing.”

A Practical Comment Handling Protocol

If I were putting this into a team working agreement, I would make it this small:

1. Every comment gets classified before it gets fixed.
2. Product behavior comments update spec.md first.
3. Architecture comments update plan.md first.
4. Sequencing comments update tasks.md first.
5. Code comments either fix implementation or trigger explicit spec reconciliation.
6. New scope becomes a follow-up spec unless the team reopens the current scope.
7. /speckit.analyze runs before implementation and after major post-implementation spec changes.

And I would add one rule that saves a lot of pain:

If reviewers disagree about which artifact owns the comment,
pause and classify it together.

That tiny pause is much cheaper than letting the comment mutate three files inconsistently.

Example: Before and After Implementation

Imagine the feature is:

Allow finance admins to export monthly invoices as CSV.

During pre-implementation review, comments arrive:

PM: Customers need to filter by billing entity.
Security: Exports must be audit logged.
Engineer: The current invoice query cannot handle six-month ranges.
QA: We need failure cases for empty months and partial invoice data.

Route them like this:

PM comment --------> spec.md acceptance criteria
Security comment --> plan.md constraints + tasks.md audit task
Engineer comment --> plan.md technical approach
QA comment -------> tasks.md test coverage

After implementation, comments arrive:

Reviewer: The code allows non-admin users to call the endpoint.
PM: Can we also schedule this every month?
Engineer: The task said streaming, but the implementation buffers in memory.
QA: The CSV has no test for invoices with missing tax IDs.

Handle them like this:

non-admin access ----> code defect, fix before merge
scheduled exports ---> new follow-up spec
buffering mismatch --> reconcile plan vs implementation, then fix or document
missing tax ID test -> add test task and test

The important move is not the table itself. The important move is refusing to treat all comments as the same kind of work.

Alternatives to GitHub Spec Kit

Spec Kit is strong when you want an open, repo-local, agent-flexible workflow.

It is not always the best fit.

Kiro

Kiro is a spec-driven development environment that guides work through requirements, design, and tasks before implementation. It may be a better fit if your team wants the spec workflow embedded directly in an IDE experience instead of wiring Spec Kit into different coding agents.

Choose Kiro when:

• you want a more integrated product experience
• you want specs, design, and tasks in one guided environment
• your team is comfortable adopting a specific AI IDE

Tessl

Tessl pushes harder toward specs as primary artifacts. Its public materials describe specs with component descriptions, capabilities, linked tests, and APIs.

Choose Tessl when:

• you want to explore spec-as-source workflows
• you are comfortable with a stronger methodology layer
• generated implementation from structured specs is the main experiment

BDD and Gherkin

BDD is older, proven, and very useful when the main risk is shared understanding of user behavior. Cucumber describes BDD as collaboration around concrete examples of how the system should behave.

Choose BDD when:

• examples matter more than architecture
• QA, product, and engineering need a shared language
• executable acceptance tests are the main artifact

Example:

Feature: Invoice CSV export

  Scenario: Finance admin exports invoices for an empty month
    Given I am a finance admin
    And there are no invoices for March 2026
    When I export March invoices as CSV
    Then the CSV contains only the header row
    And the export is audit logged

Contract-First API Development

For API-heavy work, OpenAPI, AsyncAPI, gRPC proto files, and contract testing may be more precise than a broad feature spec. Specmatic positions this as turning API specifications into executable contracts and compatibility checks.

Choose contract-first when:

• API compatibility is the main risk
• multiple teams depend on the interface
• CI should enforce the contract automatically

Lightweight RFCs and ADRs

Sometimes Spec Kit is too much.

For a small internal change, a lightweight RFC plus one Architecture Decision Record may be enough.

Choose this when:

• the implementation is small
• there is one main decision
• the risk is architectural memory, not feature ambiguity

My Recommended Default

For a real team receiving many comments before and after implementation, I would use this operating model:

Before implementation:
  comment -> classify -> update spec/plan/tasks -> checklist -> analyze

During implementation:
  discovery -> classify -> flow-back if still in scope -> tests

After implementation:
  defect -> fix code/tests
  missed requirement -> update spec/plan/tasks/tests
  changed requirement -> flow-forward follow-up spec
  new capability -> new spec or issue

In other words:

Do not ask "how do we answer this comment?"
Ask "which source of truth should this comment change?"

That one question makes Spec Kit feel less like a folder of markdown files and more like an actual delivery system.

Gaps I Still See

Spec Kit is useful, but the feedback loop still needs team conventions.

The main gaps I see are:

• No universal rule for artifact persistence. The docs intentionally leave this to teams, which is flexible but can confuse new adopters.
• Issue and PR traceability is still mostly a team practice. There has been community interest in tighter GitHub Issues integration, but teams should not wait for first-party automation before linking specs, issues, and PRs.
• Post-implementation reconciliation needs discipline. Spec Kit can structure the workflow, but it cannot force a team to update the right artifact after a late requirement change.
• Large comment sets need facilitation. When many stakeholders comment, someone still needs to classify, deduplicate, and decide what blocks implementation.

The section I would add in a future version is a worked example with an actual PR review thread, showing how each comment moves into spec.md, plan.md, tasks.md, code, tests, or a follow-up feature.

Final Takeaway

Spec Kit is not valuable because it creates more documents.

It is valuable because it gives feedback somewhere specific to go.

Before implementation, use feedback to make the spec, plan, and task list sharper.

After implementation, use feedback to decide whether the code is wrong, the spec is incomplete, the requirement changed, or the next feature has started.

That distinction is the difference between “we got a lot of comments” and “we improved the system.”

Source List

Validated against these sources on June 10, 2026.

Primary Spec Kit Sources

• GitHub Spec Kit README
• GitHub Spec Kit Documentation
• GitHub Spec Kit Quick Start Guide
• What is Spec-Driven Development?
• Spec Persistence Models
• GitHub Blog: Spec-driven development with AI

Community and Alternative Sources

• Martin Fowler: Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl
• GitHub Spec Kit discussion: Evolving specs
• GitHub Spec Kit issue: Tighter integration between GitHub Issues and Spec Kit created branches
• Kiro docs: Specs
• Tessl: Spec-Driven Development with Tessl
• Tessl blog: Tessl launches spec-driven framework and registry
• Cucumber: Behaviour-Driven Development
• Specmatic: Contract Driven Development