Skip to main content

SCOPE Stage

The SCOPE stage analyzes the issue and creates a structured implementation plan.

Purpose​

Before any code is written, the Scoper agent:

  1. Understands the problem
  2. Researches the codebase
  3. Identifies files to modify
  4. Creates implementation steps
  5. Notes open questions

Process​

┌─────────────────────────────────────────────────────────────┐
│                      SCOPE STAGE                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   1. Read Issue                                              │
│      ├─ Title, description                                   │
│      ├─ Comments, context                                    │
│      └─ Acceptance criteria                                  │
│                                                              │
│   2. Analyze Codebase                                        │
│      ├─ Search for related code                              │
│      ├─ Understand architecture                              │
│      └─ Identify dependencies                                │
│                                                              │
│   3. Create ScopeResult                                      │
│      ├─ Summary                                              │
│      ├─ Files to modify                                      │
│      ├─ Files to create                                      │
│      ├─ Implementation steps                                 │
│      ├─ Testing strategy                                     │
│      └─ Open questions                                       │
│                                                              │
│   4. Post to Linear                                          │
│      └─ Formatted plan as comment                            │
│                                                              │
│   5. Signal Completion                                       │
│      └─ Create .goblin/scope-complete                        │
│                                                              │
└─────────────────────────────────────────────────────────────┘

ScopeResult Schema​

The Scoper outputs a structured JSON:

class ScopeResult(BaseModel):
    summary: str                              # 1-2 sentence summary
    files_to_modify: list[FileChange]         # Existing files to change
    files_to_create: list[FileChange]         # New files to create
    dependencies_to_add: list[Dependency]     # New packages
    estimated_complexity: Literal["low", "medium", "high"]
    open_questions: list[str]                 # Questions needing clarification
    implementation_steps: list[ImplementationStep]
    risks: list[str]                          # Potential concerns
    testing_strategy: str                     # How to test

FileChange​

class FileChange(BaseModel):
    path: str                    # File path
    description: str             # What changes
    change_type: str             # "modify", "create", "delete"

ImplementationStep​

class ImplementationStep(BaseModel):
    order: int                   # Step number
    description: str             # What to do
    files: list[str]            # Files involved
    estimated_lines: int | None  # LOC estimate

Example Output​

{
  "summary": "Add user authentication using JWT tokens",
  "files_to_modify": [
    {
      "path": "src/middleware.py",
      "description": "Add auth middleware",
      "change_type": "modify"
    }
  ],
  "files_to_create": [
    {
      "path": "src/auth.py",
      "description": "JWT token handling",
      "change_type": "create"
    }
  ],
  "dependencies_to_add": [
    {"name": "pyjwt", "version": "^2.8.0"}
  ],
  "estimated_complexity": "medium",
  "open_questions": [
    "Should we use refresh tokens?"
  ],
  "implementation_steps": [
    {
      "order": 1,
      "description": "Create auth module with JWT validation",
      "files": ["src/auth.py"],
      "estimated_lines": 50
    },
    {
      "order": 2,
      "description": "Add authentication middleware",
      "files": ["src/middleware.py"],
      "estimated_lines": 30
    }
  ],
  "risks": [
    "Need to handle token expiration gracefully"
  ],
  "testing_strategy": "Unit tests for JWT validation, integration tests for auth flow"
}

Open Questions​

If the Scoper identifies questions:

  • They are logged as warnings
  • Included in Linear comment
  • Builder proceeds with reasonable assumptions
  • Questions visible for human review

Linear Comment Format​

## Scope Complete: ENG-123

### Summary
Add user authentication using JWT tokens

### Files to Modify
- `src/middleware.py` - Add auth middleware

### Files to Create
- `src/auth.py` - JWT token handling

### Implementation Steps
1. Create auth module with JWT validation
2. Add authentication middleware
3. Add login/logout endpoints
4. Write unit tests

### Complexity
Medium

### Open Questions
- Should we use refresh tokens?

### Testing Strategy
Unit tests for JWT validation, integration tests for auth flow

---
_Proceeding to BUILD stage_

Scoper Prompt​

The Scoper receives a prompt that includes:

  • Issue details
  • Codebase structure
  • Instructions for creating ScopeResult
  • GOBLIN_NOTES.md instructions

Completion Signal​

When done, the Scoper creates:

.goblin/scope-complete

This triggers the PipelineRunner to start the BUILD stage.

Configuration​

# Enable CEO review before SCOPE (optional)
goblin specialist spawn --type ceo --issue ENG-123

Next Steps​