agentleFS
tddworkstddworks/asc-cli/.claude/skills/fix-bug/SKILL.md

fix-bug

Skill393 starsChanged 37 days agoApache-2.0View on GitHub

Guide for fixing bugs in asc-swift (App Store Connect CLI) with Chicago School TDD: reproduce, find the layer that owns the rule, write a failing `should …` test, fix minimally. Use this skill when: (1) User reports a bug or unexpected `asc` / `asc web-server` output (2) A field is missing, wrong or `null` compared to App Store Connect (3) User asks "fix this bug" or "this doesn't work correctly" (4) An SDK bump added enum cases or fields the domain doesn't mirror yet For enhancements use improvement; for new commands use implement-feature.

45 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use build-feature, write-tests and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • sirakinbSkill

    build-feature

    Autonomous task loop that picks ready tasks, implements them, updates progress.txt, commits, and repeats. Use when asked to 'build feature', 'run the loop', or 'implement these tasks'.

    Also in 5 projects that use this

  • SentrySkill

    write-tests

    Write tests following project conventions. Use when adding new tests or modifying existing ones.

    Also in 6 projects that use this

  • JetBrainsSkill

    create-plan

    Research the codebase and create an implementation plan with architecture notes, design document, and track decomposition. Use when starting a new feature or large change.

    Also in 4 projects that use this

  • JasonPaffSkill

    implement-plan

    Execute implementation plan with structured tracking and validation using subagent architecture

    Also in 3 projects that use this

  • GitHubSkill

    refactor

    Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements.

    Also in 9 projects that use this

  • DockerSkill

    review-changes

    Review uncommitted or recently committed documentation changes for correctness, coherence, and style compliance. Use before creating a PR to catch issues. "review my changes", "review the diff", "check the fix before submitting", "does this look right".

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 45 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    The real response: when the SDK answer matters, capture it and turn it into the test fixture with placeholder data (1234567890, app-1, …

    line 23
  2. Distinctive:

    If the right fix changes the JSON schema (renames or removes a field), that is a breaking change for agents: ask the user before fixing.

    line 38
  3. Very specific:

    Run it and watch it fail for the right reason (the assertion, or the missing symbol the test names).

    line 67
  4. Distinctive:

    Fix it once for both surfaces: if the CLI and REST disagree, route both through the same code rather than patching each.

    line 76
  5. Very specific:

    Run the suite again (green), then swift test (all green).

    line 77

“Common” is measured: kept by at least 6 in 10 of the 45 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Fix a Bug in asc-swift

1. REPRODUCE & LOCATE  →  2. FAILING TEST (Red)  →  3. FIX & VERIFY (Green)

Phase 1: Reproduce & Locate

  1. Reproduce with the real command: make run ARGS="<command> --pretty", or the REST route under asc web-server.
  2. Expected: what the person or agent should see — the App Store Connect state, in our JSON schema.
  3. Actual: what asc prints instead.
  4. The real response: when the SDK answer matters, capture it and turn it into the test fixture with placeholder data (1234567890, app-1, ver-1) — never IDs, names, emails or text from a real account. Never log a key, JWT or cookie while investigating.

Find the layer that owns the rule

Fix the bug where the rule lives, not at a call site that happens to show it:

SymptomOwnerTest lives in
Wrong isLive / isEditable / isPendingthe state enum in Sources/Domain/…Tests/DomainTests/…
Missing or wrong next command / _linksthe model's structuredAffordances (CLI and REST both derive from it)Tests/DomainTests/…
Field null, wrong value, missing parent IDthe SDK*Repository mapper in Sources/Infrastructure/…Tests/InfrastructureTests/…
A value App Store Connect sends shows as nulla domain enum missing a case the SDK has (mapped via init(rawValue:) → nil)Domain + Infrastructure
Wrong flag parsing, table, or JSON shapethe command in Sources/ASCCommand/Commands/…Tests/ASCCommandTests/…
CLI right but REST wrong (or the reverse)the controller in Commands/Web/Controllers/ — CLI and REST should share one path; make themTests/ASCCommandTests/…

If the right fix changes the JSON schema (renames or removes a field), that is a breaking change for agents: ask the user before fixing.

Phase 2: Failing Test (Red)

Name the test after the correct behaviour, not the bug: should <outcome> when <the situation that showed the bug> → Naming tests. State-based only — stub the answer, assert the result, no verify().

Example — after the SDK bump to 4.5.1, App Store Connect can send koreaAgeRatingOverride: TWELVE_PLUS, which our domain enum lacks:

@Test func `should show a Korea override of twelve plus when App Store Connect sends it`() async throws {
    // Given - the response that triggers the bug
    let stub = StubAPIClient()
    stub.willReturn(AgeRatingDeclarationResponse(
        data: AgeRatingDeclaration(
            type: .ageRatingDeclarations, id: "decl-1",
            attributes: .init(koreaAgeRatingOverride: .twelvePlus)
        ),
        links: .init(this: "")
    ))
    let repo = SDKAgeRatingDeclarationRepository(client: stub)

    // When - the real mapper reads it
    let declaration = try await repo.getDeclaration(appInfoId: "info-1")

    // Then - the EXPECTED value (fails before the fix: it is nil)
    #expect(declaration.koreaAgeRatingOverride == .twelvePlus)
}

Run it and watch it fail for the right reason (the assertion, or the missing symbol the test names). Report the red line to the user before touching Sources/:

swift test --filter 'SDKAgeRatingDeclarationRepositoryTests'

Phase 3: Fix & Verify (Green)

  1. Minimal change at the owner from Phase 1 — no unrelated refactors.
  2. Fix it once for both surfaces: if the CLI and REST disagree, route both through the same code rather than patching each.
  3. Run the suite again (green), then swift test (all green). A pre-existing flaky test that shows up is not part of this fix — mention it, don't fix it here.
  4. Docs in the same change: docs/features/<x>/README.md Gotchas when the person could hit it again; make docs if a flag changed.

Checklist

  • Reproduced with the real command (or REST route)
  • Owner of the rule identified (table above)
  • should … test written for the correct behaviour, with placeholder fixture data
  • Test FAILS before the fix — red reported to the user
  • Minimal fix at the owner; CLI and REST share the path
  • Test PASSES; full swift test green
  • Feature README updated if the person could hit it again
  • One line under ## [Unreleased] → ### Fixed in CHANGELOG.md: the effect in the person's words, with an absolute issue or PR link

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.