---
name: astrology-lens-planets-in-transit
description: Reading lens — Robert Hand's Planets in Transit source lookup. Use inside astrology-reading-compose and transit-reading flows when interpreting transit-to-natal aspects or house transits from the astro-sources wiki.
version: 0.1.0
author: Hermes Agent + Alex
license: MIT
metadata:
  hermes:
    tags: [astrology, lens, transits, robert-hand, planets-in-transit, source-grounded]
    related_skills: [astrology-reading-compose, astral-transit-calendar, astral-chart-api, astral-tenant-kb, llm-wiki]
---

# Astrology Lens — Planets in Transit

A **lens**, not a full reading. It looks up Robert Hand's *Planets in Transit: Life Cycles for Living* in the `astro-sources` wiki and emits structured, citation-backed transit delineation claims for the compose layer to weave into prose.

## When to use

Use this lens when the prompt involves:

- a transit-to-natal aspect, e.g. “Neptune opposing my Ascendant,” “Saturn square Moon,” “Mars trine Neptune”;
- a transiting planet through a natal house, e.g. “Jupiter in my 7th house”;
- a transit calendar/background transit reading where each exact hit needs source-grounded interpretive support;
- user explicitly says “Robert Hand,” “Planets in Transit,” or asks what the book says.

Do **not** use this lens for static natal placements, decans, rulership chains, or Human Design. It complements, not replaces, `astrology-lens-rulership-chains` and `astrology-lens-decans-36-faces`.

## Source package

Preferred source locations, in order:

1. `$ASTRAL_ASTRO_SOURCES_WIKI` when set by an Astral tenant container.
2. `/data/hermes/shared-wikis/astro-sources` inside Astral tenant Hermes homes.
3. `/home/avalon/astro-sources-wiki` on Alex's main VPS / astro profile.

Required files:

- `concepts/planets-in-transit.md`
- `raw/books/planets-in-transit/indexes/transit-heading-index.json`
- `raw/books/planets-in-transit/reports/transit-heading-quality-report.md`
- `raw/books/planets-in-transit/chapters/*.md`

The heading index is the fast path. It was generated by `scripts/planets_in_transit_heading_qa.py` and has normalized OCR-damaged headings while preserving verbatim page-level evidence.

## Lens contract

**Input:** one or more transit hits from `astral-transit-calendar` / `astral-chart-api`, or a natural-language request that can be normalized to a heading.

**Output:** structured JSON-like claims for the compose layer:

```json
{
  "lens": "planets-in-transit",
  "version": "0.1.0",
  "claims": [
    {
      "kind": "transit-source-delineation",
      "heading": "Neptune Opposition Ascendant",
      "transitingPlanet": "Neptune",
      "aspect": "Opposition",
      "natalPoint": "Ascendant",
      "summary": "Close relationships, advice, partnership and legal/open-enemy situations become foggy; the remedy is explicit communication and critical awareness.",
      "source": "Planets in Transit",
      "pdfPage": 484,
      "chapterFile": "raw/books/planets-in-transit/chapters/chapter-12-neptune.md"
    }
  ],
  "citations": [
    {
      "base": "astro-sources",
      "page": "raw/books/planets-in-transit/chapters/chapter-12-neptune.md",
      "heading": "Neptune Opposition Ascendant",
      "pdfPage": 484
    }
  ],
  "gaps": []
}
```

**Do not emit final reading prose by itself.** Return source-grounded claims and citations; `astrology-reading-compose` weaves the final answer.

## Retrieval method

1. Resolve the source wiki root using the location order above.
2. Load `raw/books/planets-in-transit/indexes/transit-heading-index.json`.
3. Normalize the requested heading:
   - transit-to-natal aspect: `<Transiting Planet> <Aspect> <Natal Point>`;
   - house transit: `<Transiting Planet> in the <House Ordinal> House`.
4. Lookup the canonical heading in the index.
5. Read only the section span from the chapter file when quotes or a detailed summary are needed.
6. Emit citation metadata: `base=astro-sources`, chapter path, heading, PDF page, line numbers when available.

A helper script is bundled at `scripts/query_planets_in_transit.py`:

```bash
python3 scripts/query_planets_in_transit.py "Neptune Opposition Ascendant"
```

## Known source QA notes

- The compiled/search artifacts have **719 canonical transit sections**: 599 aspect sections and 120/120 house sections.
- The only unresolved theoretical major-aspect grid gap is `Pluto Trine Neptune`; do not fabricate it from general astrology knowledge.
- Four OCR-damaged headings were normalized in compiled artifacts while preserved in verbatim page JSONL:
  - `Venus Opposition Mercury`
  - `Mars Trine Neptune`
  - `Neptune Trine Uranus`
  - `Neptune Trine Neptune`
- Seven rare/slow outer-planet sections are structurally short because the book itself gives little or no delineation. If a hit resolves to one of these, say the source is sparse rather than padding with generic meaning.

## Hard rules

- Always cite `Planets in Transit` with chapter path + PDF page.
- Do not quote from the book unless you actually read the section text.
- Do not fill missing/short sections with unsourced generic astrology while presenting it as Hand.
- Keep tenant privacy separate: the source wiki is shared/read-only; client birth data, transit calendars, and readings are saved only under `ASTRAL_KB_ROOT` / tenant `knowledge/`.
- For broad transit readings, combine this lens with live transit calculations from `astral-transit-calendar`; do not infer active transits from the book.

## Verification

- [ ] `transit-heading-index.json` exists and contains the requested heading.
- [ ] The cited chapter file exists.
- [ ] PDF page and heading are included in citations.
- [ ] If the requested heading is missing, the gap is explicit and not silently replaced.
- [ ] No final prose is emitted as a standalone reading outside `astrology-reading-compose`.