feat(cli): add shep doctor command for self-diagnosis and auto-fix by arielshad · Pull Request #438 · shep-ai/shep

arielshad · 2026-03-20T23:12:39Z

Summary

Add shep doctor top-level CLI command that lets users report operational failures, auto-creates GitHub issues on shep-ai/cli, optionally invokes an AI agent to attempt a fix, and opens a PR with the proposed fix
Supports both maintainers (direct push to shep-ai/cli) and external contributors (auto-fork + cross-fork PR) via push access auto-detection
Collects diagnostic context (recent failed agent runs, CLI version, system info) to produce structured bug reports
Supports feature-specific diagnostics via --feature-id option — scopes agent run collection to a specific feature and includes feature context in the GitHub issue

Changes

Domain Layer (TypeSpec)

New DoctorDiagnosticReport, FailedRunSummary, and SystemInfo value objects in TypeSpec
Extended WorkflowConfig with doctorMaxFixAttempts setting
Added featureId and featureName optional fields to DoctorDiagnosticReport for feature-scoped diagnostics

Application Layer

New DoctorDiagnoseUseCase orchestrating the full diagnose → issue → clone/fork → agent fix → PR flow
Injects IFeatureRepository to resolve feature by ID or prefix when --feature-id is provided
Filters failed agent runs by featureId when feature-scoped
Includes "Feature Context" section in issue body with feature ID and name

Infrastructure Layer

GitHubIssueCreatorService — wraps gh issue create with error mapping (not found, auth, network)

Presentation Layer

doctor.command.ts — Commander.js command with [description] positional arg, --fix/--no-fix/--workdir/--feature-id options
Interactive prompt fallback when no description argument provided
Progress spinners and result display (issue URL, PR URL)

DI Container

All new services and use case registered in container.ts

Test Coverage

11 unit tests for GitHubIssueCreatorService (success paths, error mapping, cause preservation)
29 unit tests for DoctorDiagnoseUseCase (diagnostic collection, issue creation, maintainer/contributor flows, agent invocation, graceful degradation, temp dir cleanup, feature-specific diagnostics)
31 unit tests for doctor CLI command (structure, prerequisites, description collection, fix gate flags, workdir, feature-id option, result display, error handling)
19 integration tests for doctor workflow (end-to-end maintainer flow, contributor flow, issue-only flow, failure graceful degradation, service ordering)

Total: 90 new tests, all passing

Test plan

pnpm build compiles without errors
pnpm validate (lint + format + typecheck + tsp) passes
Doctor-specific tests: 79/79 passing (3 test files)
CI pipeline passes all checks

Evidence

Area	Evidence
TypeSpec types	DoctorDiagnosticReport with featureId/featureName, FailedRunSummary, SystemInfo value objects generated correctly
CLI registration	`shep doctor` registered as top-level command, `--help` shows all options including `--feature-id`
Unit tests	90/90 passing across service, use case, and command layers
Integration tests	19/19 passing covering both maintainer and contributor flows
Build	Clean compilation with no errors

Spec: specs/073-shep-doctor/

🤖 Generated with Claude Code

github-actions · 2026-03-20T23:19:11Z

Dev Release Published

Artifact	Version	Install
npm	`1.135.2-pr438.e15badd`	`npm install -g @shepai/cli@1.135.2-pr438.e15badd`

_{Published from commit c2a610e | View CI}

github-actions · 2026-03-20T23:40:48Z

Dev Release Published

Artifact	Version	Install
npm	`1.135.2-pr438.f43bc1e`	`npm install -g @shepai/cli@1.135.2-pr438.f43bc1e`

_{Published from commit 1ac4c2e | View CI}

github-actions · 2026-03-22T08:33:10Z

Dev Release Published

Artifact	Version	Install
npm	`1.136.0-pr438.9e52ee5`	`npm install -g @shepai/cli@1.136.0-pr438.9e52ee5`

_{Published from commit 9ef1135 | View CI}

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…utor flows Address user feedback: shep doctor now supports both shep maintainers (who push directly to shep-ai/cli without forking) and external contributors (who fork first). Uses gh api permission check to auto-detect push access and select the appropriate flow automatically. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…p doctor Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…octor 15 tasks across 6 phases: TypeSpec domain models, service interface ports, infrastructure implementations, use case orchestration, CLI command with DI wiring, and integration testing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…fig extension Add DoctorDiagnosticReport TypeSpec value object with FailedRunSummary and SystemInfo sub-models for structured diagnostic data collection. Extend WorkflowConfig with optional doctorMaxFixAttempts field (default 1) to control fix retry behavior in the shep doctor workflow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add IGitHubIssueService interface with createIssue method, error types, and result DTO. Extend IGitHubRepositoryService with checkPushAccess and forkRepository methods for maintainer vs contributor flow detection. Extend IGitPrService with createPrFromArgs for programmatic cross-fork PR creation. Includes implementations and comprehensive interface tests. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Implement GitHubIssueCreatorService wrapping gh issue create with typed error handling (GH_NOT_FOUND, AUTH_FAILURE, NETWORK_ERROR, CREATE_FAILED). Register IGitHubIssueService in DI container. Add comprehensive unit tests covering success and error paths. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add tests for checkPushAccess (true/false/error fallback paths), forkRepository (new fork, existing fork, error handling), and createPrFromArgs (same-repo, cross-fork with --repo flag, error handling). All three methods were implemented in phase 2 and now have comprehensive test coverage. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

… and fix workflow Implement DoctorDiagnoseUseCase orchestrating the full shep doctor workflow: - Collect diagnostics (failed agent runs, CLI version, system info) - Create structured GitHub issue on shep-ai/cli - Auto-detect push access for maintainer vs contributor flow - Clone/fork repo, invoke AI agent, commit and create PR - Graceful degradation on failures, temp directory cleanup 24 unit tests covering both flows, edge cases, and NFR compliance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add top-level `shep doctor` CLI command that diagnoses shep failures, creates GitHub issues, and optionally attempts automated fixes. Register DoctorDiagnoseUseCase in DI container and wire command into the CLI program. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Clean ANSI codes from evidence files and add complete headers with test suite names, file paths, dates, and structured pass/fail markers. All 8 evidence files updated with fresh test runs confirming: - 11/11 github-issue-creator service tests passing - 24/24 doctor use case unit tests passing - 28/28 doctor command unit tests passing - 19/19 doctor integration tests passing - TypeSpec types verified in generated output - CLI help and command registration confirmed - Build succeeds with no errors Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

TypeSpec compiler v0.60.1 now emits double-quoted strings in enum values. Regenerated output.ts to match current compiler output and prevent freshness check failures. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…diagnostics When a feature ID (or prefix) is provided via --feature-id, doctor scopes its diagnostic collection to agent runs associated with that feature. The feature name and ID are included in the GitHub issue body under a new "Feature Context" section, and failed runs are filtered to only those matching the feature. - Add featureId/featureName optional fields to DoctorDiagnosticReport TypeSpec model - Inject IFeatureRepository into DoctorDiagnoseUseCase for feature lookup - Support both full ID and prefix-based feature resolution - Filter failed agent runs by featureId when provided - Include feature context section in formatted GitHub issue body - Add --feature-id <id> CLI option to doctor command - Add 5 new unit tests for feature-specific diagnostics - Add 3 new command tests for --feature-id option - Update integration test mocks for new IFeatureRepository dependency Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

… diagnostics Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…r use case Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-03-24T10:13:07Z

Dev Release Published

Artifact	Version	Install
npm	`1.150.1-pr438.a45c5a8`	`npm install -g @shepai/cli@1.150.1-pr438.a45c5a8`

_{Published from commit 34fb45e | View CI}

Merge origin/main into feat/shep-doctor, resolving conflicts in IGitHubRepositoryService interface and implementations. Main added getViewerPermission + GitHubPermissionError while this branch added checkPushAccess + forkRepository + GitHubForkError — both sets are retained. Updated all mock objects across test files to include the complete interface. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The recoverAll tests fail when run inside a shep-spawned child process because SHEP_SKIP_RECOVERY=1 is inherited from the parent, causing recoverAll to early-return. Save and restore the env var around the recoverAll describe block. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-03-24T17:44:24Z

Dev Release Published

Artifact	Version	Install
npm	`1.151.2-pr438.6135e39`	`npm install -g @shepai/cli@1.151.2-pr438.6135e39`

_{Published from commit e95f2e2 | View CI}

arielshad and others added 26 commits March 24, 2026 11:56

docs(specs): analyze repository and define spec for shep doctor feature

d6c96f3

docs(specs): define requirements and product questions for shep doctor

71da98c

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs(specs): research technical decisions and library choices for she…

df0e9b0

…p doctor Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

test(domain): add integration tests for doctor workflow

3747abf

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore(specs): capture evidence for shep doctor feature tasks

9209e05

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore(specs): re-capture evidence for shep doctor feature tasks

7143e60

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore(specs): add feature tracking yaml for shep doctor

2b692e0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs(specs): add design spec for enriched doctor diagnostics

06bc188

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs(specs): add implementation plan and fix spec review issues

e18aa9c

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(tsp): add agent-run-detail and worker-log-entry models to doctor…

4971067

… diagnostics Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

test(cli): add failing tests for enriched doctor diagnostics collection

1a57201

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(cli): add enriched diagnostic collection and formatting to docto…

e28a127

…r use case Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

test(cli): add integration test for enriched doctor diagnostics

d04ab7a

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(cli): address lint issues from enriched diagnostics

ee39822

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(cli): add missing git-pr-service mock methods after rebase onto main

34fb45e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

arielshad force-pushed the feat/shep-doctor branch from b876b2a to 34fb45e Compare March 24, 2026 10:06

arielshad and others added 2 commits March 24, 2026 19:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): add shep doctor command for self-diagnosis and auto-fix#438

feat(cli): add shep doctor command for self-diagnosis and auto-fix#438
arielshad wants to merge 28 commits into
mainfrom
feat/shep-doctor

arielshad commented Mar 20, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 20, 2026

Uh oh!

github-actions Bot commented Mar 20, 2026

Uh oh!

github-actions Bot commented Mar 22, 2026

Uh oh!

github-actions Bot commented Mar 24, 2026

Uh oh!

github-actions Bot commented Mar 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

arielshad commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Domain Layer (TypeSpec)

Application Layer

Infrastructure Layer

Presentation Layer

DI Container

Test Coverage

Test plan

Evidence

Uh oh!

github-actions Bot commented Mar 20, 2026

Dev Release Published

Uh oh!

github-actions Bot commented Mar 20, 2026

Dev Release Published

Uh oh!

github-actions Bot commented Mar 22, 2026

Dev Release Published

Uh oh!

github-actions Bot commented Mar 24, 2026

Dev Release Published

Uh oh!

github-actions Bot commented Mar 24, 2026

Dev Release Published

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

arielshad commented Mar 20, 2026 •

edited

Loading