← all skills

transit-tarot-spread

/home/avalon/.hermes/skills/astrology/transit-tarot-spread/SKILL.md · raw

Transit-Driven Tarot Spread

The sky picks the cards. The number of qualifying transits picks the shape.

When to use

User asks: "draw me a tarot spread from my current transits", "what tarot cards are the sky pulling for me right now", "transit tarot reading", or any variant of let the transits dictate a tarot pull. This is not a generic daily-card skill — it's specifically transit-driven and uses decan correspondences.

For a written transit reading without cards → astral-transit-snapshot. For decan ↔ tarot mapping reference → concepts/decan-tarot-correspondences.md in astro-sources-wiki.

Selection rules (the contract)

  1. Bodies considered (transiting AND natal): Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn. Exclude outer planets (Uranus/Neptune/Pluto) and Nodes from both sides.
  2. Natal points also valid: Asc, MC (as natal targets only).
  3. Aspects: conjunction (0°), opposition (180°), trine (120°), square (90°), sextile (60°).
  4. Orb: 2.0° max, all bodies. Tighter orb ranks higher, but the primary sort key is time-to-exact (see below).
  5. No cap on card count — if 8 qualify, draw 8. If 0 qualify, say so and stop (do NOT pad).
  6. Decan side = transiting planet. The card pulled corresponds to the transiting planet's current decan (sign + face-i/ii/iii by degree).
  7. Sequence ordering = combined score weighted toward planetary speed. See ranking formula below.
  8. No centered/anchor card. No reversals.

Ranking formula

For each qualifying aspect:

exact_diff_deg = target_aspect_angle - current_angular_separation     # signed
hours_to_exact = (exact_diff_deg / transit_speed_deg_per_day) * 24    # signed: + applying, - separating
score = abs(hours_to_exact) if applying else abs(hours_to_exact) * 1.5

Sort ascending by score. Lowest = position 1 in the spread.

This natively combines (a) how close the aspect is to exact and (b) how fast the transiting body is moving, because a fast planet covers a 1° orb in hours while Saturn takes weeks. Moon at 1° orb applying ≈ a few hours; Saturn at 1° orb applying ≈ ~2 weeks. The Moon wins position 1.

Separating aspects are penalized 1.5× because they are fading rather than building.

Layout shapes (count-driven, semantically positioned)

Layouts are not abstract geometry — each count maps to a recognized classical spread, with named slots. Rank order maps to slot order below (rank-1 hit → slot 1).

N Spread Slot 1 Slot 2 Slot 3 Slot 4 Slot 5 Slot 6 Slot 7 Slot 8
1 Daily Draw the signal
2 Side-by-side pair left right
3 Past / Present / Future (row) past (L) present (C) future (R)
4 Four-card cross situation (L) obstacle (R) advice (bottom) outcome (top)
5 Five-card cross with center situation (center) unconscious infl. (L) conscious infl. (R) way through (bottom) outcome / resolution (top)
6 Two rows of three top-L top-C top-R bot-L bot-C bot-R
7 Horseshoe arc past present hidden obstacles external advice outcome
8 Two rows of four top-1 top-2 top-3 top-4 bot-1 bot-2 bot-3 bot-4

Positions ascend in rank order — the lowest-score (fastest-to-exact-and-tightest) aspect always lands in slot 1.

Captions on the composite image show the slot label, the card name, the transit aspect, and the orb.

Workflow

  1. Time + subject. Capture UTC + local time. Resolve subject via astral-tenant-kb (default = self).
  2. Pull current transits. curl -sS https://transit-list-demo.apps.poofc.com/api/transits/current — includes speed.
  3. Load natal chart (cached or computed via the chart API).
  4. Compute aspects (Sun–Saturn only on both sides; include Asc/MC as natal targets). Apply 2° orb.
  5. Rank by the formula above.
  6. Map each transiting planet to its decan card using concepts/decan-tarot-correspondences.md: - decan index = floor(degree_in_sign / 10) → I (0), II (1), III (2) - Look up card + asset path from the table.
  7. Pick layout shape from the count table.
  8. Generate composite image via scripts/compose_spread.py (see scripts/). Output → /tmp/transit-tarot-spread-<timestamp>.png.
  9. Reply with: - Header line (subject + local + UTC) - Numbered list of positions: **N. <Card>** — <Transit planet> <aspect> natal <body> · orb <X>°<Y>′ · <applying|separating> · exact in ~<hours/days> - One short paragraph: what this constellation of cards is saying (lead with position 1). - MEDIA:/tmp/transit-tarot-spread-<timestamp>.png so the image renders.

Pitfalls

Verification