Activity

1. mnriem

   added

   bug-assess

   on Aug 11, 2026
2. github-actions commented on Aug 11, 2026

   

   github-actionsbot

   on Aug 11, 2026 – with GitHub Actions

   Contributor

   More actions

   Bug assessment — claude-argument-hint-fold: Valid · severity high

   ---

   Bug Assessment: Claude ARGUMENT_HINTS fallback injects into folded description scalar

   • Slug: claude-argument-hint-fold
   • Created: 2026-08-11T12:35:57Z
   • Source: issue [Bug]: #3991 still reproduces on 0.16.2 — Claude ARGUMENT_HINTS fallback injects into a folded description scalar (wrap presets without explicit argument-hint) #4044
   • Verdict: valid
   • Severity: high

   Report (summarized)

   Issue #3991 (Claude argument-hint corruption in wrap presets) was closed by PR #3996, but the fix is a no-op for the exact configuration that triggered the original report. Two conditions combine:

   1. Bundled core command templates carry no argument-hint frontmatter — hints live in the hardcoded ARGUMENT_HINTS dict in the Claude integration. So the PR [bug-fix] Fix preset-wrap-drops-argument-hint: inherit argument-hint from core template #3996 inheritance-allowlist fix has nothing to inherit, and argument-hint is absent from the frontmatter dict when it reaches serialization.
   2. The ARGUMENT_HINTS fallback (inject_argument_hint) operates on the already-serialized YAML string by string-scanning for the first line starting with description: and inserting the hint on the next line. When yaml.safe_dump folds a long description across multiple lines, the injected line lands inside the continuation of the folded scalar — producing either invalid YAML (plain scalar) or silent key corruption (quoted scalar).

   Symptom

   inject_argument_hint inserts argument-hint: directly after the description: line in the serialized YAML, but for descriptions long enough to be folded by yaml.safe_dump the injected line falls inside the multi-line scalar, either breaking YAML parsing entirely or silently merging the hint text into the description value.

   Reproduction

   1. Create a fresh project: specify init --here --integration claude --script sh --ignore-agent-tools --force
   2. Create a wrap preset with a description ≥ ~150 characters (enough to trigger YAML folding) and strategy: wrap but no explicit argument-hint.
   3. Apply the preset: specify preset add --dev ./presets-src/demo-wrap
   4. Inspect the generated skill: python3 -c "import yaml; print(yaml.safe_load(open('.claude/skills/speckit-specify/SKILL.md').read().split('---')[1]))"

   Expected: argument-hint is a separate key with the correct value.

   Actual (plain scalar): invalid YAML — yaml.parser.ParserError: expected , but found ''

   Actual (quoted scalar, e.g. description contains #): YAML parses but argument-hint key is absent; the hint line is absorbed into the description string.

   [NEEDS CLARIFICATION: Whether 0.16.2 is the latest release or if a 0.16.3+ exists with any partial mitigation.]

   Suspected Code Paths

   • src/specify_cli/integrations/claude/__init__.py:69–114 (inject_argument_hint) — The post-serialization string-scan insertion logic. It matches only the first description: line but does not account for the fact that yaml.safe_dump may have wrapped that description across multiple continuation lines before the next top-level key.
   • src/specify_cli/integrations/claude/__init__.py:194–215 (post_process_skill_content) — Calls inject_argument_hint after the skill content is already fully serialized; by this point the frontmatter dict is no longer accessible.
   • src/specify_cli/_utils.py:71–78 (dump_frontmatter) — Uses yaml.safe_dump with no width override, so the default 80-character fold width applies; long descriptions fold freely.
   • src/specify_cli/agents.py:458–482 (apply_argument_hint) — The structured path that sets argument-hint in the frontmatter dict before serialization; confirmed to be a no-op for bundled core commands because they carry no argument-hint in their template frontmatter.

   Root Cause Hypothesis

   inject_argument_hint assumes that the serialized description: value fits on a single line. When yaml.safe_dump wraps a long description, the injection point is inside the scalar's continuation, not after it. The fix in PR #3996 addressed the inheritance path (preset frontmatter → composed frontmatter dict) but did not address the fallback path where ARGUMENT_HINTS injects after serialization. Confidence: high — the code paths are clear and the two failure modes are mechanistically explained by the interaction between yaml.safe_dump's folding and single-line string injection.

   Proposed Remediation

   Preferred: Move ARGUMENT_HINTS injection to happen before YAML serialization, at the same structured level as apply_argument_hint. Concretely, in _render_skill (or wherever skill_frontmatter is built for a given template stem), look up the stem in ARGUMENT_HINTS and set skill_frontmatter["argument-hint"] directly. Then dump_frontmatter serializes the key safely as a proper YAML entry. inject_argument_hint (the string-based fallback) can remain for the case where a pre-rendered SKILL.md string arrives without the key, but it should be a last-resort — and ideally inject_argument_hint should be made fold-aware regardless (scan past continuation lines before inserting).

   Alternatives:

   • Make inject_argument_hint fold-aware: After finding description:, advance past all continuation lines (lines that start with whitespace or that are part of a block scalar), then insert after the last continuation line. More surgical but fragile — YAML scalar folding rules are subtle.
   • Force single-line descriptions in dump_frontmatter: Pass width=float("inf") to yaml.safe_dump to disable folding. This prevents the symptom but hides long descriptions awkwardly in generated files.

   Files likely to change:

   • src/specify_cli/integrations/claude/__init__.py — primary fix location; modify _render_skill or _build_skill_fm to inject argument-hint into the frontmatter dict before dump_frontmatter is called, and/or harden inject_argument_hint.
   • tests/integrations/test_integration_claude.py — add regression test composing a core template (e.g. specify) with a description long enough to fold, asserting: (a) the output parses as valid YAML, (b) argument-hint is a top-level key, (c) description contains only the preset's description text.

   Tests to add or update:

   • Regression test: test_inject_argument_hint_folded_description — call inject_argument_hint (or the full preset-compose + install cycle) with a description ≥ 150 characters and verify valid YAML output with a correct argument-hint key.
   • Regression test: test_inject_argument_hint_quoted_folded_description — same but with a #-containing description that forces quoting.
   • Parity test: verify the structured path (apply_argument_hint via frontmatter dict) and the fallback path (inject_argument_hint via string) produce identical YAML for the same hint.

   Risks & Considerations

   • Not data-loss, but correctness regression: generated SKILL.md files may be silently wrong (description absorbs hint text) without any error, and users won't notice until Claude's argument-hint UI feature fails to appear.
   • Scope: affects only the Claude integration and only when post_process_skill_content triggers the ARGUMENT_HINTS fallback — i.e., wrap presets for bundled core commands without explicit argument-hint. First-party direct install and presets that declare argument-hint explicitly are unaffected.
   • The workaround is stable: declaring argument-hint explicitly in the preset frontmatter triggers the structured apply_argument_hint path and completely avoids inject_argument_hint. No user data is at risk.
   • API surface: the fix is internal; no public API or CLI interface changes.

   Open Questions

   • [NEEDS CLARIFICATION: Is there a width parameter already passed anywhere to dump_frontmatter that might partially mitigate folding in some cases?]
   • [NEEDS CLARIFICATION: Does _render_skill have access to the template stem at call time, or does the stem need to be threaded through from the caller?]

   Generated by 🐛 Assess Bug from Labeled Issue for issue #4044 · 107.5 AIC · ⌖ 11 AIC · ⊞ 34.1K · ◷
3. github-actions

   added

   severity-high

   on Aug 11, 2026
4. chelsealong

   added a commit that references this issue on Aug 11, 2026

   fix(claude): also skip unindented blank lines in description scalar

   ...

   1f19ab0
5. mnriem

   closed this as completedin #4045on Aug 11, 2026
6. pull

   added a commit that references this issue on Aug 11, 2026

   fix(claude): make argument-hint injection fold-aware for long descrip…

   ...

   This issue will close once commit bd595cf is merged into the 'main' branch.

   bd595cf