Skip to content

feat(syncing-skills-with-hub): add diff-only mode for submodule projects #21

@WesleyMFrederick

Description

@WesleyMFrederick

Problem

The syncing-skills-with-hub skill gates out submodule projects entirely ("Do NOT use when .claude is a git submodule"). However, the skill's discovery and diff steps (a-g) are project-type-agnostic. Only the sync/commit steps (h-k) are submodule-incompatible. Users cannot use the skill to compare skills even when they only want diffs, not sync.

Reproduction Steps

  1. In a project where .claude is a submodule, invoke /syncing-skills-with-hub
  2. Claude reads scope gate: "Do NOT use when .claude is a git submodule"
  3. Skill is skipped entirely (see bug(skills): user's explicit skill invocation silently ignored due to scope conflict #17 for the silent-ignore bug)
  4. User loses access to the diff/classification capability

Root Cause

The skill bundles two concerns — diffing (read-only analysis) and syncing (write operations) — under a single scope gate. The gate rejects both even though only syncing is submodule-incompatible.

Architecture Principles Violated

Baseline violates:

  • ^extension-over-modification: Rather than extending the skill with a diff-only mode, the entire skill is gated out. The read-only capability is lost alongside the write capability.
  • ^interface-segregation: Diff (read) and sync (write) are separate concerns bundled under one scope gate. Users who need only diffs are blocked by a sync constraint.
  • ^single-responsibility: The skill mixes read-only analysis (steps a-g) with write operations (steps h-k) under one "When to Use" section.

Ideal incorporates:

  • ^extension-over-modification: Add diff-only mode that runs steps a-g, stops at summary table.
  • ^interface-segregation: Separate scope gates — diff-only works for all project types; sync requires non-submodule.
  • ^single-responsibility: Clear separation between analysis phase and action phase.

Expected Behavior

Skill supports a diff-only mode that runs discovery (a) + classify (b-f) + summary table (g) for any project type, including submodules. Sync steps (h-k) remain gated to non-submodule projects.

Related

Note

The diff-only mode was exactly what the user needed in this session. They wanted to see what was different before deciding to sync the submodule. The skill already had the capability — it was just gated out unnecessarily.


Acceptance Criteria

  • Skill supports diff-only mode for submodule projects (steps a-g)
  • Scope gate updated: diff-only works everywhere, sync requires non-submodule
  • For submodule projects, skill stops at summary table and recommends git-sync-submodule for sync
  • Non-submodule projects continue to work as before (full a-k flow)

Definition of Done

  • Skill SKILL.md updated with diff-only mode
  • Tested with subagent evaluation in a submodule project
  • Committed with conventional commit

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions