Skip to content

Improve SF API/CA API AI-assisted update command #3433

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
kdaviduik wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Improve SF API/CA API AI-assisted update command #3433

kdaviduik wants to merge 1 commit into from
+774 −1,618

Conversation

@kdaviduik
Copy link
Contributor

@kdaviduik kdaviduik commented Feb 3, 2026 •
edited
Loading

WHY are these changes introduced?

The existing .claude/commands/apis-version-update.md (1618 lines) had significant issues:

  • LLM hallucinations: The guide encouraged Claude to suggest fixes and analyze errors, leading to incorrect suggestions
  • Duplicate sections: Build steps appeared 13+ times throughout the document
  • Overly complex templates: PR and issue templates were so detailed they weren't being followed

Related: Feedback from #3281 (2025-10 API update) where hallucination issues were observed.

WHAT is this pull request doing?

Replaces the 1618-line command with a 304-line skill (81% reduction):

Before After
.claude/commands/apis-version-update.md .claude/skills/apis-version-update/SKILL.md
1618 lines 304 lines
Build steps: 13+ occurrences Build steps: 1 occurrence
No anti-hallucination guidance Explicit directive at top
Complex issue templates Minimal template: exact changelog text only

Key improvements:

  • Anti-hallucination directive: Explicit constraints to copy exact text, never add analysis
  • Consolidated build steps: Single occurrence with clear checkpoint
  • Strengthened checkpoints: "report EXACT error... Do NOT diagnose"
  • Minimal child issue template: Prevents AI from adding interpretation
  • Clear structure: "8 Tracking Phases" vs "9 Implementation Steps"

HOW to test your changes?

  1. Invoke the skill: /apis-version-update
  2. Verify the skill loads and displays the streamlined guide
  3. Check that anti-hallucination directive is prominently displayed

Checklist

  • I've read the Contributing Guidelines
  • I've considered possible cross-platform impacts (Mac, Linux, Windows)
  • I've added a changeset if this PR contains user-facing or noteworthy changes
  • I've added tests to cover my changes
  • I've added or updated the documentation

@shopify
Copy link
Contributor

shopify bot commented Feb 3, 2026 •
edited
Loading

Oxygen deployed a preview of your 2026-01-update branch. Details:

Storefront Status Preview link Deployment details Last update (UTC)
Skeleton (skeleton.hydrogen.shop) ✅ Successful (Logs) Preview deployment Inspect deployment February 4, 2026 3:53 AM

Learn more about Hydrogen's GitHub integration.

@kdaviduik
refactor(claude): streamline API version update guide into skill
2528d9e 
Replace 1618-line command with 304-line skill (81% reduction).

The old guide had issues with LLM hallucinations (suggesting fixes,
analyzing errors), duplicate sections (build steps appeared 13+ times),
and overly complex templates. The new skill:

- Adds explicit anti-hallucination directive at the top
- Consolidates build steps to appear exactly once
- Uses minimal child issue template to prevent AI interpretation
- Clarifies "8 Tracking Phases" vs "9 Implementation Steps"
- Adds handoff note for phases 3-8 requiring manual execution
- Strengthens checkpoints: "report EXACT error... Do NOT diagnose"
@kdaviduik kdaviduik changed the title Streamline API version update guide into skill Improve SF API/CA API AI-assisted update command Feb 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kdaviduik