Skip to content

docs: add concurrency guidance and lock contention warnings to skills#1156

Merged
stack72 merged 1 commit intomainfrom
skill-factory-pattern-concurrency-guidance
Apr 9, 2026
Merged

docs: add concurrency guidance and lock contention warnings to skills#1156
stack72 merged 1 commit intomainfrom
skill-factory-pattern-concurrency-guidance

Conversation

@stack72
Copy link
Copy Markdown
Contributor

@stack72 stack72 commented Apr 9, 2026

Summary

  • Adds a design checkpoint to the swamp-model skill's Workflow Example that prompts users to consider concurrency before creating a model — asking whether methods will run concurrently or be long-running, and guiding them to the factory pattern
  • Updates the factory pattern description to call out both data reuse AND concurrency as motivations (separate instances = separate locks)
  • Adds a lock contention warning to the workflow data-chaining reference, clarifying that steps on the same model serialize on the per-model lock despite being in the same job

Addresses swamp.club/lab#43 — users hitting model locks during long-running operations because they didn't know to split concerns into separate model instances.

Test plan

  • deno fmt --check passes
  • deno lint passes
  • deno run test passes (4280 tests)
  • Verify skill triggers the design checkpoint when a user asks to create a model with multiple methods

🤖 Generated with Claude Code

The swamp-model skill now prompts users with a design checkpoint before
model creation — asking whether methods will run concurrently or be
long-running, and guiding them to the factory pattern if so. The factory
pattern description is updated to call out both data reuse and
concurrency as motivations. The workflow data-chaining reference now
warns that steps on the same model serialize on the per-model lock.

Closes swamp.club/lab#43

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copy link
Copy Markdown

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

Blocking Issues

None.

Suggestions

  1. SKILL.md exceeds 500-line limit.claude/skills/swamp-model/SKILL.md is already 539 lines on main, and this PR adds ~18 net lines (bringing it to ~557). CLAUDE.md requires keeping SKILL.md under 500 lines, splitting detailed content into references/ files. The new "Design check" section (16 lines) is a good candidate to move into a reference file (e.g., references/concurrency-design.md) with a one-line pointer from SKILL.md. This is a pre-existing violation so it shouldn't block this PR, but worth addressing in a follow-up.

Notes

  • Content is technically accurate: the per-model exclusive lock behavior and factory pattern guidance for parallelism are correct and address a real user pain point (swamp.club/lab#43).
  • The lock contention warning in data-chaining.md is a valuable addition — the previous text ("Steps within a job run in parallel") was misleading without the serialization caveat.
  • No code changes, so no test/type-check/lint concerns.
  • No security issues.
  • No libswamp import boundary concerns (documentation-only change).

@stack72 stack72 merged commit c66cf3c into main Apr 9, 2026
10 checks passed
@stack72 stack72 deleted the skill-factory-pattern-concurrency-guidance branch April 9, 2026 15:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant