Skip to main content

Pause

System command used by SpecWeave to pause increments when blocked.

Synopsis​

"Pause this"
System Command

This is primarily a system command used by SpecWeave internally. SpecWeave automatically pauses work when it detects blockages. You typically don't need to call this manually.

Description​

The pause command temporarily suspends work on an active increment. SpecWeave calls this automatically when it detects you're blocked.

SpecWeave automatically pauses when:

  • Missing dependencies (API keys, credentials, configuration)
  • Waiting for external approvals or responses
  • Persistent compilation or test failures
  • You explicitly indicate "I'm blocked" or "waiting for..."

Manual pause only for:

  • Business decisions (strategic pivot, deprioritization)
  • Cases where SpecWeave hasn't detected blockage

Options​

<increment-id> (required)​

The increment to pause (e.g., 0007-payment-integration).

specweave pause 0007-payment-integration

--reason <text> or -r <text>​

Reason for pausing (highly recommended).

specweave pause 0007 --reason "Waiting for Stripe production API keys"
Always Provide a Reason

While optional, always provide a reason. It documents context for your future self and team.

--force or -f​

Update reason if already paused.

# First pause
specweave pause 0007 --reason "Waiting for API keys"

# Later, update reason
specweave pause 0007 --reason "Waiting for API keys (IT ticket #1234)" --force

Examples​

Example 1: Automatic Pause (Typical)​

# You're working on implementation (or said "start implementing")
$ specweave do

# SpecWeave detects missing Stripe API keys
SpecWeave: I need Stripe production API keys to continue

   Options:
   1. Provide keys now
   2. Let me pause this work and file IT ticket
   3. Skip this task

# You choose option 2
$ 2

# SpecWeave automatically runs:
# specweave pause 0007-payment-integration \
#   --reason "Waiting for Stripe production API keys (IT ticket #1234)"

Increment 0007-payment-integration automatically paused
Reason: Waiting for Stripe production API keys (IT ticket #1234)
No longer counts toward active limit
I've filed IT ticket #1234 for you

What SpecWeave did:

  • Detected blockage automatically
  • Paused increment (status -> paused)
  • Filed IT ticket for you
  • Freed WIP limit slot
  • Suggested next action

Example 2: Manual Pause (Business Decision)​

# Strategic decision to deprioritize (or say "pause this")
$ specweave pause 0005-ui-redesign \
  --reason "Pausing UI redesign - focusing on backend performance per CEO directive"

Pausing increment 0005-ui-redesign...

Increment 0005-ui-redesign paused
Reason: Pausing UI redesign - focusing on backend performance per CEO directive
No longer counts toward active limit

When to manually pause:

  • Strategic business decisions
  • Explicit deprioritization from leadership
  • Cases where SpecWeave can't detect the business context

Example 3: Temporary Deprioritization​

# Urgent hotfix takes priority
specweave pause 0008-feature-x \
  --reason "Pausing for hotfix 0009, will resume after deploy"

# Work on hotfix
specweave inc "0009-critical-bug-fix"
specweave do

# Resume later (or say "resume work")
specweave resume 0008

Example 4: Update Reason (Force)​

# Initial pause
specweave pause 0007 --reason "Waiting for API access"

# Got more details
specweave pause 0007 \
  --reason "Waiting for API access (ETA: 3 days, contact: [email protected])" \
  --force

# Output:
Increment 0007 is already paused
   Previous reason: Waiting for API access
   Paused at: 2025-11-04T10:00:00Z

Reason updated

Behavior​

Status Transitions​

Valid transitions:

  • active -> paused
  • paused -> paused (with --force)

Invalid transitions:

  • completed -> paused
  • abandoned -> paused (use resume first)

Metadata Changes​

// Before pause
{
  "id": "0007-payment-integration",
  "status": "active",
  "type": "feature",
  "created": "2025-11-01T10:00:00Z",
  "lastActivity": "2025-11-04T09:00:00Z"
}

// After pause
{
  "id": "0007-payment-integration",
  "status": "paused",
  "type": "feature",
  "created": "2025-11-01T10:00:00Z",
  "lastActivity": "2025-11-04T10:00:00Z",
  "pausedReason": "Waiting for API keys",
  "pausedAt": "2025-11-04T10:00:00Z"
}

WIP Limit Impact​

# Before pause
$ specweave status
Active (1): 0007-payment-integration
WIP Limit: 1/1

# Try to start new work
$ specweave inc "0008-feature"
Cannot create! WIP limit reached

# Pause current work (or say "pause this")
$ specweave pause 0007 --reason "Blocked"

# After pause
$ specweave status
Paused (1): 0007-payment-integration
WIP Limit: 0/1

# Now can start new work
$ specweave inc "0008-feature"
Created!

Error Handling​

Already Paused​

$ specweave pause 0007 --reason "Blocked"
Increment 0007 is already paused
   Previous reason: Waiting for API keys
   Paused at: 2025-11-04T10:00:00Z

   Use --force to update the reason

Solution: Add --force to update reason.

Cannot Pause Completed​

$ specweave pause 0001
Cannot pause increment 0001
   Current status: completed
   Only active increments can be paused

Solution: Increment is already done. Nothing to pause.

Cannot Pause Abandoned​

$ specweave pause 0003
Cannot pause increment 0003
   Current status: abandoned
   Only active increments can be paused

   Resume it first: specweave resume 0003 (or say "resume work")

Solution: Resume first, then pause.

Best Practices​

1. Always Document Why​

# Bad - no context
specweave pause 0007

# Good - clear context
specweave pause 0007 --reason "Waiting for Stripe prod API keys (IT#1234, ETA: 3 days)"

Why:

  • Future you won't remember why
  • Team needs context for standups
  • Retrospectives benefit from clear blockers

2. Include Actionable Info​

Good reasons include:

  • What you're waiting for
  • Who can unblock
  • When expected resolution
# Excellent
specweave pause 0007 \
  --reason "Waiting for Stripe prod API keys (IT ticket #1234, contact: [email protected], ETA: Nov 6)"

3. Review Paused Work Weekly​

# Check paused increments (or say "what's the status?")
$ specweave status

Paused (3):
  0003-kubernetes [feature]
     Reason: Waiting for DevOps approval
     Paused: 45 days ago  # Too long!

Action:

  • If blockage resolved -> resume (or say "resume work")
  • If no longer relevant -> abandon (or say "abandon this")
  • If still valid -> update reason with new ETA

4. Keep Paused Count Low​

Rule of thumb: Max 2-3 paused increments

If you have 5+ paused increments, something is wrong:

  • Too many parallel initiatives?
  • Too many external dependencies?
  • Not abandoning obsolete work?

Common Scenarios​

Scenario 1: Blocked by Another Team​

# Blocked by backend team (or say "pause this")
specweave pause 0007-frontend-feature \
  --reason "Waiting for backend API (ticket BACK-123, owner: @john)"

# Check in 2 days
$ specweave status
Paused: 0007-frontend-feature (2 days ago)

# API ready, resume (or say "resume work")
$ specweave resume 0007

Scenario 2: Waiting for Decision​

# Stakeholder hasn't decided
specweave pause 0005-new-dashboard \
  --reason "Waiting for VP approval on design mockups (meeting: Nov 5)"

# Decision made (or say "resume work")
$ specweave resume 0005

Scenario 3: Multiple Pauses (Bad Pattern)​

# Anti-pattern: pausing everything
$ specweave status
Paused (8):  # Way too many!
  0001 (90 days ago)
  0003 (45 days ago)
  0005 (30 days ago)
  ...

Fix: Audit and clean up

# Abandon old/irrelevant work (or say "abandon this")
$ specweave abandon 0001 --reason "Requirements changed, no longer needed"
$ specweave abandon 0003 --reason "Postponed indefinitely"

# Resume what's actually important
$ specweave resume 0005

Integration with Other Commands​

pause -> status​

$ specweave pause 0007 --reason "Blocked"
$ specweave status

Paused (1):
  0007-payment-integration [feature]
     Reason: Blocked

pause -> resume​

$ specweave pause 0007 --reason "Waiting for API"
# ... later ...
$ specweave resume 0007

Resumed
Was paused for: Waiting for API

pause -> abandon​

$ specweave pause 0007 --reason "Waiting for API"
# Decision: not doing this anymore
$ specweave abandon 0007 --reason "Requirements changed"

See Also​

  • resume - Restart paused work
  • abandon - Cancel work permanently
  • status - Check current status
  • Status Management Guide - Complete workflow guide

Summary​

Key Points:

  • Use pause for temporary blockages
  • Always provide a clear reason
  • Paused increments don't count toward WIP limit
  • Review paused work weekly
  • Keep paused count low (2-3 max)

Command:

specweave pause <increment-id> --reason "<clear explanation>"

Philosophy:

Pausing isn't failure--it's explicit acknowledgment of reality. Document it, move on, return when unblocked.