adaptive-enforcement-lab/implementation-patterns

Implementation Patterns

When to Use This Skill

| Pattern | Best For | Tradeoff | | --------- | ---------- | ---------- | | Check-Before-Act | Creating resources | Race conditions possible | | Upsert | APIs with atomic operations | Not universally available | | Force Overwrite | Content that can be safely replaced | Destructive if misused | | Unique Identifiers | Natural deduplication | ID logic can be complex | | Tombstone Markers | Multi-step operations | Markers need cleanup |

---

Implementation

Five patterns for making operations idempotent. Each has tradeoffs; choose based on your constraints.

---

Pattern Overview

| Pattern | Best For | Tradeoff | | --------- | ---------- | ---------- | | Check-Before-Act | Creating resources | Race conditions possible | | Upsert | APIs with atomic operations | Not universally available | | Force Overwrite | Content that can be safely replaced | Destructive if misused | | Unique Identifiers | Natural deduplication | ID logic can be complex | | Tombstone Markers | Multi-step operations | Markers need cleanup |

---

Quick Reference

Check-Before-Act

The most common pattern. Check if the target state exists before attempting to create it.

if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
  git checkout -B "$BRANCH" "origin/$BRANCH"
else
  git checkout -b "$BRANCH"
fi

Create-or-Update (Upsert)

Use APIs or commands that handle both cases atomically.

gh release create v1.0.0 --notes "Release" || gh release edit v1.0.0 --notes "Release"

Force Overwrite

Don't check, just overwrite. Safe when overwriting with identical content is acceptable.

git push --force-with-lease origin "$BRANCH"

Unique Identifiers

Generate deterministic IDs so duplicate operations target the same resource.

BRANCH="update-$(sha256sum file.txt | cut -c1-8)"

Tombstone/Marker Files

Leave markers indicating operations completed.

MARKER=".completed-$RUN_ID"
[ -f "$MARKER" ] && exit 0
# Do work...
touch "$MARKER"

---

Choosing a Pattern

See examples.md for detailed code examples.

| Scenario | Recommended Pattern | | ---------- | ------------------- | | Creating resources (PRs, branches, files) | Check-Before-Act | | Updating existing resources | Upsert or Force Overwrite | | Operations with natural keys | Unique Identifiers | | Complex multi-step operations | Tombstone Markers | | API supports atomic operations | Upsert |

Combine Patterns

Real-world automation often combines multiple patterns. A workflow might use Check-Before-Act for PR creation, Force Overwrite for branch updates, and Unique Identifiers for naming.

Pattern Overview

| Pattern | Best For | Tradeoff | | --------- | ---------- | ---------- | | Check-Before-Act | Creating resources | Race conditions possible | | Upsert | APIs with atomic operations | Not universally available | | Force Overwrite | Content that can be safely replaced | Destructive if misused | | Unique Identifiers | Natural deduplication | ID logic can be complex | | Tombstone Markers | Multi-step operations | Markers need cleanup |

---

Quick Reference

Check-Before-Act

The most common pattern. Check if the target state exists before attempting to create it.

if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
  git checkout -B "$BRANCH" "origin/$BRANCH"
else
  git checkout -b "$BRANCH"
fi

Create-or-Update (Upsert)

Use APIs or commands that handle both cases atomically.

gh release create v1.0.0 --notes "Release" || gh release edit v1.0.0 --notes "Release"

Force Overwrite

Don't check, just overwrite. Safe when overwriting with identical content is acceptable.

git push --force-with-lease origin "$BRANCH"

Unique Identifiers

Generate deterministic IDs so duplicate operations target the same resource.

BRANCH="update-$(sha256sum file.txt | cut -c1-8)"

Tombstone/Marker Files

Leave markers indicating operations completed.

MARKER=".completed-$RUN_ID"
[ -f "$MARKER" ] && exit 0
# Do work...
touch "$MARKER"

---

Choosing a Pattern

See examples.md for detailed code examples.

| Scenario | Recommended Pattern | | ---------- | ------------------- | | Creating resources (PRs, branches, files) | Check-Before-Act | | Updating existing resources | Upsert or Force Overwrite | | Operations with natural keys | Unique Identifiers | | Complex multi-step operations | Tombstone Markers | | API supports atomic operations | Upsert |

Combine Patterns

Real-world automation often combines multiple patterns. A workflow might use Check-Before-Act for PR creation, Force Overwrite for branch updates, and Unique Identifiers for naming.

Techniques

Pattern Overview

| Pattern | Best For | Tradeoff | | --------- | ---------- | ---------- | | Check-Before-Act | Creating resources | Race conditions possible | | Upsert | APIs with atomic operations | Not universally available | | Force Overwrite | Content that can be safely replaced | Destructive if misused | | Unique Identifiers | Natural deduplication | ID logic can be complex | | Tombstone Markers | Multi-step operations | Markers need cleanup |

---

Quick Reference

Check-Before-Act

The most common pattern. Check if the target state exists before attempting to create it.

if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
  git checkout -B "$BRANCH" "origin/$BRANCH"
else
  git checkout -b "$BRANCH"
fi

Create-or-Update (Upsert)

Use APIs or commands that handle both cases atomically.

gh release create v1.0.0 --notes "Release" || gh release edit v1.0.0 --notes "Release"

Force Overwrite

Don't check, just overwrite. Safe when overwriting with identical content is acceptable.

git push --force-with-lease origin "$BRANCH"

Unique Identifiers

Generate deterministic IDs so duplicate operations target the same resource.

BRANCH="update-$(sha256sum file.txt | cut -c1-8)"

Tombstone/Marker Files

Leave markers indicating operations completed.

MARKER=".completed-$RUN_ID"
[ -f "$MARKER" ] && exit 0
# Do work...
touch "$MARKER"

---

Choosing a Pattern

flowchart TD
    A[Need idempotency] --> B{API has upsert?}
    B -->|Yes| C[Use Upsert]
    B -->|No| D{Safe to overwrite?}
    D -->|Yes| E[Use Force Overwrite]
    D -->|No| F{Natural unique key?}
    F -->|Yes| G[Use Unique Identifiers]
    F -->|No| H{Multi-step operation?}
    H -->|Yes| I[Use Tombstone Markers]
    H -->|No| J[Use Check-Before-Act]

    %% Ghostty Hardcore Theme
    style A fill:#5e7175,color:#f8f8f3
    style B fill:#fd971e,color:#1b1d1e
    style C fill:#a7e22e,color:#1b1d1e
    style D fill:#fd971e,color:#1b1d1e
    style E fill:#e6db74,color:#1b1d1e
    style F fill:#fd971e,color:#1b1d1e
    style G fill:#65d9ef,color:#1b1d1e
    style H fill:#fd971e,color:#1b1d1e
    style I fill:#9e6ffe,color:#1b1d1e
    style J fill:#65d9ef,color:#1b1d1e

| Scenario | Recommended Pattern | | ---------- | ------------------- | | Creating resources (PRs, branches, files) | Check-Before-Act | | Updating existing resources | Upsert or Force Overwrite | | Operations with natural keys | Unique Identifiers | | Complex multi-step operations | Tombstone Markers | | API supports atomic operations | Upsert |

Combine Patterns

Real-world automation often combines multiple patterns. A workflow might use Check-Before-Act for PR creation, Force Overwrite for branch updates, and Unique Identifiers for naming.

Examples

See examples.md for code examples.

References

• Source Documentation
• AEL Patterns