Charon/docs/plans/current_spec.md

Current Specification

Status: 🔧 IN PROGRESS - Staticcheck Pre-Commit Integration Last Updated: 2026-01-11 (Auto-generated) Previous Work: Docs-to-Issues Workflow Fix Validated (PR #461 - Archived)

---

Active Project: Staticcheck Pre-Commit Integration

Priority: 🟡 MEDIUM - Code Quality Improvement Reported: User experiencing staticcheck errors in VS Code Problems tab Objective: Integrate staticcheck into pre-commit hooks to catch issues before commit

Problem Statement

Staticcheck errors are appearing in VS Code's Problems tab but are not being caught by pre-commit hooks. This allows code with static analysis issues to be committed, reducing code quality and causing CI failures or technical debt accumulation.

Current Gaps:

• ✅ Staticcheck IS enabled in golangci-lint (.golangci.yml line 14)
• ✅ Staticcheck IS running in CI via golangci-lint-action (quality-checks.yml line 65-70)
• ❌ Staticcheck is NOT running in local pre-commit hooks
• ❌ golangci-lint pre-commit hook is in manual stage only (.pre-commit-config.yaml line 72)
• ❌ No standalone staticcheck pre-commit hook exists

Why This Matters:

• Developers see staticcheck warnings/errors in VS Code editor
• These issues are NOT blocked at commit time
• Creates inconsistent developer experience
• Delays feedback loop (errors found in CI instead of locally)
• Increases cognitive load (developers must remember to check manually)

---

Current State Assessment

Pre-Commit Hooks Analysis

File: .pre-commit-config.yaml

Existing Go Linting Hooks:

1. go-vet (Lines 39-44) - ✅ ACTIVE (runs on every commit)

   • Runs on every commit for .go files
   • Fast (< 5 seconds)
   • Catches basic Go issues

2. golangci-lint (Lines 72-78) - ❌ MANUAL ONLY

   • Includes staticcheck (per .golangci.yml)
   • Only runs with: pre-commit run golangci-lint --all-files
   • Slow (30-60 seconds) - reason for manual stage
   • Runs in Docker container

GolangCI-Lint Configuration

File: backend/.golangci.yml

Staticcheck Status:

• ✅ Line 14: - staticcheck (enabled in linters.enable)
• ✅ Lines 68-70: Test file exclusions (staticcheck excluded from _test.go)

Other Enabled Linters:

• bodyclose, gocritic, gosec, govet, ineffassign, unused, errcheck

VS Code Tasks

File: .vscode/tasks.json

Existing Lint Tasks:

• Line 204: "Lint: Go Vet" → cd backend && go vet ./...
• Line 216: "Lint: GolangCI-Lint (Docker)" → Runs golangci-lint in Docker

Missing:

• ❌ No standalone "Lint: Staticcheck" task
• ❌ No quick lint task for just staticcheck

Makefile Targets

File: Makefile

Existing Quality Targets:

• Line 138: lint-backend → Runs golangci-lint in Docker
• Line 144: test-race → Go tests with race detection

Missing:

• ❌ No staticcheck target
• ❌ No quick lint-quick target

CI/CD Integration

File: .github/workflows/quality-checks.yml

Lines 65-70:

• Runs golangci-lint (includes staticcheck) in CI
• ⚠️ continue-on-error: true means failures don't block merges
• Uses golangci-lint-action (official GitHub Action)

System Environment

Staticcheck Installation:

$ which staticcheck
# (empty - not installed)

Conclusion: Staticcheck is NOT installed as a standalone binary on the development system.

---

Root Cause Analysis

Primary Cause: Staticcheck is integrated into the project via golangci-lint but:

1. golangci-lint pre-commit hook is in manual stage due to performance (30-60s)
2. No lightweight, fast-only-staticcheck pre-commit hook exists
3. Developers see staticcheck errors in VS Code but can commit without fixing them

Contributing Factors:

1. Performance Trade-off: golangci-lint is comprehensive but slow (runs 8+ linters)
2. Manual Stage Rationale: Documented in .pre-commit-config.yaml line 67
3. Missing Standalone Tool: Staticcheck binary not installed, only available via golangci-lint
4. Inconsistent Enforcement: CI runs golangci-lint with continue-on-error: true

---

Recommended Solution: Standalone Staticcheck Pre-Commit Hook

Justification:

1. Performance: Fast enough for pre-commit (5-10s vs 30-60s for full golangci-lint)
2. Developer Experience: Aligns with VS Code feedback loop
3. Low Risk: Minimal changes, existing workflows unchanged
4. Standard Practice: Many Go projects use standalone staticcheck pre-commit

---

Implementation Plan

Phase 1: Staticcheck Installation & Pre-Commit Hook

Task 1.1: Add staticcheck installation to documentation

File: README.md Location: Development Setup section

Addition:

### Go Development Tools

Install required Go development tools:

\`\`\`bash
# Required for pre-commit hooks
go install honnef.co/go/tools/cmd/staticcheck@latest
\`\`\`

Ensure `$GOPATH/bin` is in your `PATH`:
\`\`\`bash
export PATH="$PATH:$(go env GOPATH)/bin"
\`\`\`

Task 1.2: Add staticcheck pre-commit hook

File: .pre-commit-config.yaml Location: After go-vet hook (after line 44)

      - id: staticcheck
        name: Staticcheck (Go Static Analysis)
        entry: bash -c 'cd backend && staticcheck ./...'
        language: system
        files: '\.go$'
        pass_filenames: false

---

Phase 2: Developer Tooling

Task 2.1: Add VS Code task

File: .vscode/tasks.json Location: After "Lint: Go Vet" task (after line 211)

        {
            "label": "Lint: Staticcheck",
            "type": "shell",
            "command": "cd backend && staticcheck ./...",
            "group": "test",
            "problemMatcher": ["$go"]
        },

Task 2.2: Add Makefile targets

File: Makefile Location: After lint-backend target (after line 141)

staticcheck:
	@echo "Running staticcheck..."
	cd backend && staticcheck ./...

lint-quick: staticcheck
	@echo "Quick lint complete"
	cd backend && go vet ./...

---

Phase 3: Definition of Done Updates

Task 3.1: Update checklist

File: .github/instructions/copilot-instructions.md Location: After line 91 (Pre-Commit Triage section)

3. **Staticcheck Validation**: Run VS Code task "Lint: Staticcheck" or execute `cd backend && staticcheck ./...`.
    - Fix all staticcheck errors immediately.
    - Staticcheck warnings should be evaluated and triaged.
    - This check runs automatically in pre-commit.
    - Why: Staticcheck catches subtle bugs and style issues that go vet misses.

Task 3.2: Document in Backend Workflow

File: .github/instructions/copilot-instructions.md Location: After line 36 (Backend Workflow section)

- **Static Analysis**: Staticcheck runs automatically in pre-commit hooks.
  - Run manually: `staticcheck ./...` or VS Code task "Lint: Staticcheck"
  - Staticcheck errors MUST be fixed; warnings should be triaged.

---

Phase 4: Testing & Validation

Task 4.1: Validate staticcheck installation

go install honnef.co/go/tools/cmd/staticcheck@latest
which staticcheck
staticcheck --version

Task 4.2: Test pre-commit hook

pre-commit run staticcheck --all-files

Task 4.3: Test VS Code task

1. Open Command Palette
2. Run Task → "Lint: Staticcheck"
3. Verify errors in Problems tab

Task 4.4: Test Makefile targets

make staticcheck
make lint-quick

---

Phase 5: Documentation & Communication

Task 5.1: Update CHANGELOG.md

### Added
- Pre-commit hook for staticcheck (Go static analysis)
- VS Code task "Lint: Staticcheck"
- Makefile targets: `staticcheck` and `lint-quick`

### Changed
- Dev setup now requires staticcheck installation

Task 5.2: Create implementation summary

File: docs/implementation/STATICCHECK_PRE_COMMIT_INTEGRATION.md

Task 5.3: Archive this plan

Move to docs/plans/archive/staticcheck_integration_2026-01-11.md

---

Success Criteria

1. ✅ Pre-Commit Hook:

   • Staticcheck hook added to .pre-commit-config.yaml
   • Runs automatically on .go file commits
   • Fails on staticcheck errors
   • Runtime < 15 seconds

2. ✅ Developer Tooling:

   • VS Code task "Lint: Staticcheck" created
   • Makefile targets added

3. ✅ Documentation:

   • Installation instructions added
   • Definition of Done updated
   • CHANGELOG.md updated
   • Implementation summary created

4. ✅ Validation:

   • All tools tested and verified
   • Performance benchmarked

5. ✅ Quality Checks:

   • Pre-commit passes
   • CodeQL scans pass
   • Tests pass with coverage
   • Build succeeds

---

File Reference Summary

Files to Modify:

1. .pre-commit-config.yaml (line 44: add staticcheck hook)
2. .vscode/tasks.json (line 211: add Staticcheck task)
3. Makefile (line 141: add staticcheck targets)
4. .github/instructions/copilot-instructions.md (lines 36, 91: add to DoD)
5. README.md (add installation instructions)
6. CHANGELOG.md (add unreleased changes)

Files to Create:

1. docs/implementation/STATICCHECK_PRE_COMMIT_INTEGRATION.md
2. docs/plans/archive/staticcheck_integration_2026-01-11.md

---

Performance Benchmarks

Target:

• Current pre-commit: ~5-10 seconds
• After staticcheck: ~10-20 seconds
• Maximum acceptable: 25 seconds

---

Rollback Plan

If problems occur:

1. Delete staticcheck hook from .pre-commit-config.yaml
2. Run pre-commit clean
3. Revert documentation changes
4. Rollback time: < 5 minutes

---

Risk Assessment

Overall Risk Level: 🟢 LOW

1. Performance Impact (LOW) - Benchmark before/after
2. Installation Friction (LOW) - Clear docs provided
3. False Positives (MEDIUM) - Use lint:ignore comments if needed
4. CI Misalignment (LOW) - Document version pinning

---

Phase Breakdown Timeline

Phase	Time	Dependencies
Phase 1	30 min	None
Phase 2	30 min	Phase 1
Phase 3	30 min	Phase 1
Phase 4	45 min	Phases 1-3
Phase 5	30 min	Phase 4

Total Estimated Time: 2-3 hours

---

Archive Location

Previous specifications in: docs/plans/archive/

---

Note: This specification follows Spec-Driven Workflow v1 format.