Rapid codebase assessment command (/gsd-scan)

[davesienkowski]

Pre-submission checklist

• I have searched existing issues and discussions -- this has not been proposed and declined before
• I have read CONTRIBUTING.md and understand that I must wait for approved-feature before writing any code
• I have read the existing GSD commands and workflows and confirmed this feature does not duplicate existing behavior
• This feature solves a problem for solo developers using AI coding tools, not a personal preference or workflow I happen to like

Feature name

Rapid codebase assessment command (/gsd-scan)

Type of addition

New command (slash command or CLI flag)

The solo developer problem

GSD has /gsd-map-codebase which spawns 4 parallel mapper agents and produces 7 documents -- a comprehensive but heavy operation. When a solo developer just needs a quick understanding of the tech stack and architecture before planning, the full map-codebase is overkill. There is no lightweight alternative that targets a single concern area.

What this feature adds

A new /gsd-scan command that spawns a single gsd-codebase-mapper agent for one focus area, producing targeted documents in .planning/codebase/.

Focus areas:

• tech -- produces STACK.md, INTEGRATIONS.md
• arch -- produces ARCHITECTURE.md, STRUCTURE.md
• quality -- produces CONVENTIONS.md, TESTING.md
• concerns -- produces CONCERNS.md
• tech+arch -- produces all 4 tech+arch documents (DEFAULT)

The command checks for existing documents in the target area and offers to overwrite or skip.

Example usage:

/gsd-scan
> Scanning codebase (focus: tech+arch)...
> Spawning gsd-codebase-mapper agent...
> Complete. Documents written to .planning/codebase/:
>   STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md

/gsd-scan --focus quality
> Scanning codebase (focus: quality)...
> Complete. Documents written to .planning/codebase/:
>   CONVENTIONS.md, TESTING.md

Full scope of changes

Files created:

• commands/gsd/scan.md -- slash command definition with --focus flag
• get-shit-done/workflows/scan.md -- scan workflow that spawns single mapper agent

Files modified:

• None required. The command and workflow are self-contained.

User stories

1. As a solo developer who needs a quick tech stack overview before planning, I want to run /gsd-scan --focus tech to get STACK.md and INTEGRATIONS.md without waiting for the full 4-agent map-codebase run.
2. As a solo developer reviewing code quality before a refactoring phase, I want to run /gsd-scan --focus quality to get CONVENTIONS.md and TESTING.md as targeted assessment documents.

Acceptance criteria

• /gsd-scan defaults to tech+arch focus and spawns one gsd-codebase-mapper agent
• /gsd-scan --focus tech produces only STACK.md and INTEGRATIONS.md
• /gsd-scan --focus quality produces only CONVENTIONS.md and TESTING.md
• /gsd-scan --focus concerns produces only CONCERNS.md
• Invalid focus values are rejected with an error listing valid options
• Existing documents are detected and the developer is prompted before overwriting
• Documents are written to .planning/codebase/
• The command is discoverable via /gsd-help

Which area does this primarily affect?

Core workflow (init, plan, build, verify)

Applicable runtimes

• Claude Code
• All runtimes (runtime-agnostic)

Breaking changes assessment

None. This is an entirely new command. /gsd-map-codebase continues to work unchanged for comprehensive analysis.

Maintenance burden

Low. The command delegates all analysis work to the existing gsd-codebase-mapper agent. The focus-to-document mapping is a simple static table. If new document types are added to the mapper, the mapping table needs updating.

Alternatives considered

1. Add a --focus flag to /gsd-map-codebase -- Would change existing command behavior and complicate its 4-agent parallel design. A separate lightweight command is cleaner.
2. Manual mapper agent invocation -- Requires the developer to know agent names and spawning syntax. A command encapsulates this knowledge.

Prior art and references

Replaces #1724 (which incorrectly described this as a JSON-producing scanner). Split from #1687 per maintainer feedback.

[trek-e]

✅ Approved as feature.

Clean, lightweight frontend to the existing mapper agent. Low complexity, low maintenance, practical usability improvement over the full map-codebase.

Implementation notes:

• The focus-to-document mapping should be a simple static table at the top of the workflow — easy to update
• Overwrite prompt should show file modification dates so the developer can judge staleness
• Default to tech+arch is the right call — most common pre-planning need

@davesienkowski — labeled approved-feature. You're clear to implement.