Repository navigation
chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805
Description
Activity
Feature assessment — apply-shfmt-shellcheck · Stage 1/5: Intake
Idea Intake: Apply shfmt and fix shellcheck warnings in scripts/bash
- Slug: apply-shfmt-shellcheck
- Created: 2026-10-01T17:45:16Z
- Source: chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805
- Type: improvement
Idea (as captured)
scripts/bash/*.shcurrently passes CI only becauselint.ymlruns shellcheck at--severity=error. At default severity there are 8 findings, andshfmt -dreports differences in all 6 files.Proposed: a behavior-neutral PR limited to
scripts/bash, with no CI changes. Tightening the CI severity or adding a shfmt check can be a follow-up.The issue also identifies SC2155 findings in
common.shandcreate-new-feature.sh, SC1091 findings in five scripts, and formatting differences under the repository's.editorconfig4-space indentation.Restated
Bring the six Bash scripts under
scripts/bashinto the repository's configured shfmt style and address the reported non-error shellcheck findings, while preserving behavior and leaving CI policy unchanged.Origin & Context
- Raised by: jlec
- Trigger: GitHub issue chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805 reports local shellcheck and shfmt findings and proposes a behavior-neutral cleanup.
First-Glance Unknowns
- [NEEDS CLARIFICATION: Are all six scripts intended to be formatted by the same shfmt version and configuration used to produce the report?]
- [NEEDS CLARIFICATION: Should SC1091 be resolved through shellcheck source-path configuration, annotations, or script changes?]
- [NEEDS CLARIFICATION: What regression checks are required to demonstrate behavior neutrality for the affected scripts?]
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4805 · copilot · gpt52codex · 3.43 AIC · ⌖ 12.8 AIC · ⊞ 24K · ◷
Feature assessment — apply-shfmt-shellcheck · Stage 2/5: Research
Idea Research: Apply shfmt and fix shellcheck warnings in scripts/bash
- Slug: apply-shfmt-shellcheck
- Created: 2026-10-01T17:45:16Z
- Evidence confidence (overall): medium
Users & Demand
- The request is maintainer-authored and tied to concrete local lint output, not a broad feature request — [source: chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805] (confidence: high, cited).
- The issue does not provide usage telemetry, support tickets, or additional user reports — [source: chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805] (confidence: high, cited).
Prior Art
- The repository already runs shellcheck in
.github/workflows/lint.yml, but limits it to--severity=error; the workflow comment explicitly says style findings such as SC2155 are deferred to a follow-up — [source:.github/workflows/lint.yml] (confidence: high, cited). - The repository's
.editorconfigspecifies four-space indentation for shell files, giving shfmt a documented formatting target — [source:.editorconfig] (confidence: high, cited). - The affected surface is the six tracked scripts in
scripts/bash:check-prerequisites.sh,common.sh,create-new-feature.sh,resolve-template.sh,setup-plan.sh, andsetup-tasks.sh— [source:scripts/bash/*.sh] (confidence: high, cited). - The issue reports eight default-severity shellcheck findings and shfmt differences in all six scripts; those findings are not independently reproduced in this assessment environment — [source: chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805] (confidence: medium, cited).
Market & Context
- The immediate alternative is to leave the scripts unchanged while CI continues to enforce only error-severity shellcheck findings; this avoids churn but preserves known style and analysis warnings — [source:
.github/workflows/lint.yml, chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805] (confidence: high, cited). - No external market or competitor context is relevant to this repository-maintenance request — [source: assessment scope] (confidence: medium, cited).
Data & Constraints
- The proposed change is explicitly behavior-neutral, limited to
scripts/bash, and excludes CI changes — [source: chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805] (confidence: high, cited). - The lint workflow currently checks shellcheck error severity and does not run shfmt, so this cleanup alone would not enforce continued formatting or default-severity cleanliness — [source:
.github/workflows/lint.yml] (confidence: high, cited). - The issue names SC2155 at
common.sh:71,create-new-feature.sh:217, andcreate-new-feature.sh:254, plus SC1091 in five scripts — [source: chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805] (confidence: high, cited).
Evidence Against the Idea
- Formatting and warning cleanup can create review noise or accidental behavior changes in shell scripts if the tool version or source-resolution assumptions differ from the reported environment — [source: chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805,
.editorconfig] (confidence: medium, cited). - Without a CI check for shfmt or default shellcheck severity, the cleanup may regress later — [source:
.github/workflows/lint.yml] (confidence: high, cited). - There is no independent evidence that these warnings currently cause user-facing failures — [source: chore: apply shfmt and fix shellcheck warnings in scripts/bash #4805] (confidence: high, cited).
Gaps & Open Questions
- [NEEDS CLARIFICATION: Which exact shfmt version and invocation generated the report?]
- [NEEDS CLARIFICATION: What deterministic behavior tests or smoke checks cover all affected scripts?]
- [NEEDS CLARIFICATION: Should source-resolution warnings be fixed in scripts or documented with shellcheck configuration?]
Sources
github/spec-kit#4805(host: github.com, policy: allowlisted).github/workflows/lint.yml(repository source).editorconfig(repository source)scripts/bash/*.sh(repository source)
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4805 · copilot · gpt52codex · 3.43 AIC · ⌖ 12.8 AIC · ⊞ 24K · ◷
Feature assessment — apply-shfmt-shellcheck · Stage 3/5: Problem
Problem Definition: Apply shfmt and fix shellcheck warnings in scripts/bash
- Slug: apply-shfmt-shellcheck
- Created: 2026-10-01T17:45:16Z
- Inputs used: intake.md and research.md
Problem Statement
Spec Kit maintainers receive actionable formatting and default-severity shellcheck findings across the Bash tooling, but the current lint workflow only blocks error-severity findings and does not check shfmt. This leaves known maintainability issues unresolved and makes the repository's stated shell formatting convention difficult to verify consistently.
Affected Users & Stakeholders
- Users: contributors modifying or reviewing
scripts/bash— they encounter inconsistent formatting and warnings during local analysis. - Users: maintainers operating Spec Kit's shell tooling — they carry review and regression risk from warnings that CI does not currently surface.
- Stakeholders: repository maintainers — they decide whether a behavior-neutral cleanup is worth accepting.
- Stakeholders: downstream project users — they may be affected if shell-script cleanup accidentally changes execution behavior.
Goals
- Reduce the reported default-severity shellcheck findings in the six Bash scripts.
- Align the six scripts with the repository's four-space shell formatting convention.
- Preserve existing script behavior and keep the change limited to
scripts/bash. - Improve confidence that future maintenance work starts from a clean, readable baseline.
Non-Goals
- Changing lint workflow severity or adding a shfmt CI check.
- Refactoring shell-script behavior, interfaces, or unrelated scripts.
- Adding new shell functionality or changing generated project output.
- Claiming that warning cleanup alone provides complete shell-script correctness.
Success Metrics
shfmt -dreports no differences for the six affected scripts under the repository's.editorconfigconvention (baseline: issue reports differences in all six; exact command/version unknown).- The eight issue-reported default-severity findings are resolved or explicitly justified without introducing new findings (baseline: eight reported; independent reproduction pending).
- Existing deterministic checks and representative script smoke checks remain passing (baseline: exact coverage unknown).
- The diff is confined to
scripts/bash(baseline: proposed scope).
Cost of Inaction
Known style and analysis warnings remain in the shell tooling while CI continues to report only error-severity shellcheck findings. Contributors must interpret avoidable warnings locally, and later cleanup becomes more difficult to review or may accumulate formatting drift.
Open Questions
- [NEEDS CLARIFICATION: What exact shfmt version and invocation define the expected output?]
- [NEEDS CLARIFICATION: Which behavior and smoke checks are sufficient for all six scripts?]
- [NEEDS CLARIFICATION: How should SC1091 source-resolution findings be addressed?]
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4805 · copilot · gpt52codex · 3.43 AIC · ⌖ 12.8 AIC · ⊞ 24K · ◷
Feature assessment — apply-shfmt-shellcheck · Stage 4/5: Concept
Concept: Apply shfmt and fix shellcheck warnings in scripts/bash
- Slug: apply-shfmt-shellcheck
- Created: 2026-10-01T17:45:16Z
- Recommended option: Targeted cleanup with regression checks
Options
Option A — Targeted cleanup with regression checks
+- Sketch: Format the six
scripts/bashfiles to the repository convention, address the eight reported warnings using behavior-neutral changes or documented source-resolution handling, and run focused lint plus representative deterministic checks before review.
+- Appetite: small
+- Trade-offs: Directly addresses the reported maintenance problem with limited scope and reviewable risk; it does not prevent future regressions because CI policy remains unchanged.
+- Rabbit holes: Shell source-path handling may expose assumptions about invocation directories; formatting can obscure a semantic change if the diff is not carefully reviewed.Option B — Cleanup plus enforcement
+- Sketch: Perform the targeted cleanup and also make CI enforce shfmt and broader shellcheck coverage so the baseline stays clean.
+- Appetite: medium
+- Trade-offs: Provides durable enforcement and clearer contributor feedback; expands scope beyond the issue's behavior-neutral, scripts-only proposal and may require tool-version pinning or workflow maintenance.
+- Rabbit holes: CI portability, formatter version drift, and newly surfaced warnings outside the six scripts.Option C — Do nothing / defer
+- Sketch: Leave the scripts and lint policy unchanged, accepting the reported warnings until a future maintenance pass or enforcement project.
+- Appetite: small
+- Trade-offs: Avoids immediate churn and behavior risk; preserves known maintainability debt and inconsistent local tooling results.
+- Rabbit holes: Deferred cleanup may grow, and later changes may mix formatting with functional edits.Recommendation
Recommend Option A. It matches the issue's stated scope, addresses measurable reported findings, and keeps the likely change budget small while requiring evidence of behavior neutrality. Option B is a reasonable follow-up but should be assessed separately because it changes CI policy; Option C does not improve the documented baseline.
Out of Scope (for the recommended option)
- Changes to
.github/workflows/lint.ymlor any CI severity/enforcement policy. - Formatting or warning cleanup outside
scripts/bash. - Functional refactors, interface changes, or new shell features.
- Broad shellcheck configuration changes that mask unrelated findings.
Assumptions to Validate
- The issue's shfmt invocation and version can be reproduced or a repository-compatible formatter version can be identified.
- SC1091 can be handled without weakening meaningful source validation.
- Existing focused tests or smoke checks cover the affected script entry points sufficiently to detect behavior changes.
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4805 · copilot · gpt52codex · 3.43 AIC · ⌖ 12.8 AIC · ⊞ 24K · ◷
Feature assessment — apply-shfmt-shellcheck · Stage 5/5: Decision — verdict needs-clarification
Decision: Apply shfmt and fix shellcheck warnings in scripts/bash
- Slug: apply-shfmt-shellcheck
- Decided: 2026-10-01T17:45:16Z
- Verdict: needs-clarification
- Artifacts reviewed: intake.md | research.md | problem.md | concept.md
Scorecard
Criterion Rating Justification Problem validity adequate The issue identifies concrete findings across all six Bash scripts and a documented formatting convention, though user-facing impact is not demonstrated. Evidence strength adequate The issue, lint workflow, editor configuration, and script inventory support the maintenance problem; exact tool versions and independent reproduction remain unknown. Value vs. inaction adequate Cleanup would reduce known review and maintenance friction, while inaction preserves warnings; the value is primarily maintainability rather than an observed runtime defect. Feasibility / appetite adequate A scripts-only cleanup is plausibly small and has a clear lightweight option, but source-resolution handling and behavior coverage need confirmation. Strategic fit adequate The proposal supports repository maintainability and follows existing lint conventions without changing product scope; no stronger project-level strategy evidence was found. Risk posture weak The main risks are identified, but the exact formatter/toolchain and sufficient behavior regression coverage are not yet established. Verdict & Rationale
Needs clarification. The maintenance problem is credible and the targeted concept is appropriately bounded, but the assessment should not hand off to specification until the exact shfmt baseline, SC1091 treatment, and deterministic behavior checks are confirmed. These gaps are material because a behavior-neutral shell cleanup can still alter execution semantics, and the current CI does not enforce the proposed baseline.
If needs-clarification
- Blocking questions:
- [NEEDS CLARIFICATION: Which exact shfmt version, flags, and shellcheck invocation produced the reported results?]
- [NEEDS CLARIFICATION: What focused regression or smoke checks cover each affected script and demonstrate behavior neutrality?]
- [NEEDS CLARIFICATION: Should SC1091 be resolved by source-path configuration, annotations, or script changes without suppressing meaningful diagnostics?]
+- Revisit stage: research
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4805 · copilot · gpt52codex · 3.43 AIC · ⌖ 12.8 AIC · ⊞ 24K · ◷
- added a commit that references this issue
on Oct 4, 2026
scripts/bash/*.shcurrently passes CI only becauselint.ymlruns shellcheck at--severity=error. At default severity there are 8 findings, andshfmt -dreports differences in all 6 files.common.sh:71,create-new-feature.sh:217,create-new-feature.sh:254check-prerequisites.sh:97,create-new-feature.sh:194,resolve-template.sh:6,setup-plan.sh:28,setup-tasks.sh:23.editorconfig(4-space indent)Proposed: a behavior-neutral PR limited to
scripts/bash, with no CI changes. Tightening the CI severity or adding a shfmt check can be a follow-up, as the comment inlint.ymlalready suggests.AI disclosure: drafted with Claude Code (Claude Sonnet 5.5), acting on behalf of @jlec. Findings come from running shellcheck and shfmt locally.