Directional Survey Analyzer

Directional Survey Analyzer

What this skill does

Parses minimum curvature directional survey files, validates station-to-station calculations, computes dogleg severity and tortuosity index, assesses anticollision separation factors, detects trajectory anomalies, and produces a complete wellbore position summary with deviation from plan.

When to use

• User uploads directional survey CSV, TXT, LAS, or XLSX files
• User asks to validate survey data or recompute trajectory
• User wants dogleg severity computed or plotted
• User needs anticollision check against offset wellbores
• User is reviewing deviation from the well plan

Trigger phrases

• "Analyze this directional survey"
• "Validate the wellbore trajectory"
• "Compute dogleg severity from these surveys"
• "Check anticollision for this wellbore"
• "Is the survey data clean?"
• "Show deviation from plan for this survey"
• "Compute tortuosity index for the lateral"
• "Flag any survey anomalies"
• "Recompute TVD and position from the raw survey stations"

Inputs

• Survey station file (CSV, TXT, XLSX): columns MD, INC, AZ
• Optional: well plan trajectory (CSV, XLSX)
• Optional: offset well surveys for anticollision
• Optional: geographic reference (KB elevation, northing/easting reference)
• Optional: magnetic declination and grid convergence for true north correction

Outputs

• Computed trajectory: MD, INC, AZ, TVD, NS, EW, DLS per station
• Dogleg severity summary per section
• Tortuosity index per section
• Separation factor table for each offset well (when provided)
• Deviation from plan table (MD, INC delta, AZ delta, lateral position error)
• Anomaly flags: inclination jumps, azimuth walk, missing stations, survey gaps
• Structured JSON output

Survey computations

Minimum curvature method (standard industry)

For stations i and i+1:

DL = arccos(cos(INC_2 - INC_1) - sin(INC_1) × sin(INC_2) × (1 - cos(AZ_2 - AZ_1)))

RF = (2 / DL) × tan(DL / 2)   [ratio factor, RF = 1 when DL = 0]

ΔNorth = (ΔMD / 2) × (sin(INC_1)cos(AZ_1) + sin(INC_2)cos(AZ_2)) × RF
ΔEast  = (ΔMD / 2) × (sin(INC_1)sin(AZ_1) + sin(INC_2)sin(AZ_2)) × RF
ΔTVD   = (ΔMD / 2) × (cos(INC_1) + cos(INC_2)) × RF

Dogleg severity

DLS (deg/100ft) = DL × (100 / ΔMD)

Tortuosity index

TI = Σ |DLS_i| / Total_lateral_length × 1000

Higher tortuosity = more tortuous lateral = higher drag and completion risk.

Anticollision

When offset surveys are provided:

1. Compute 3D position (NS, EW, TVD) for every station of every well
2. At each station of the subject well, find the closest approach to each offset
3. Compute separation vector and separation factor (SF):

SF = center_to_center_distance / (r_subject + r_offset)

Where r = wellbore radius (typically 0.5 ft + uncertainty ellipse radius).

Traffic light system:

• SF > 1.5: Green — safe separation
• 1.0 5° between consecutive stations |

| AZJUMP | Azimuth change > 15° between consecutive stations | | HIGHDLS | DLS > 8°/100ft in any section | | SURVEYGAP | Station spacing > 100 ft (MWD recommendation: 30–60 ft in build sections) | | NEGATIVEMD | Any station MD less than previous station | | DUPLICATESTATION | Two consecutive stations with same MD | | MISSINGSURVEYS | Expected station count based on total MD is less than actual | | AZ_WALK | Cumulative azimuth drift > 20° over 1,000 ft without planned turn |

Output schema

{
  "well_info": {
    "well_name": "string",
    "kb_elevation_ft": 0.0,
    "total_md_ft": 0.0,
    "total_tvd_ft": 0.0,
    "max_inclination_deg": 0.0,
    "max_dls_deg_100ft": 0.0,
    "lateral_tortuosity_index": 0.0
  },
  "survey_stations": [
    {
      "station": 0,
      "md_ft": 0.0,
      "inc_deg": 0.0,
      "az_deg": 0.0,
      "tvd_ft": 0.0,
      "north_ft": 0.0,
      "east_ft": 0.0,
      "dls_deg_100ft": 0.0,
      "cumulative_dogleg_deg": 0.0
    }
  ],
  "section_summary": [
    {
      "section": "string",
      "from_md_ft": 0.0,
      "to_md_ft": 0.0,
      "avg_dls_deg_100ft": 0.0,
      "max_dls_deg_100ft": 0.0,
      "tortuosity_index": 0.0,
      "avg_inc_deg": 0.0
    }
  ],
  "anticollision": [
    {
      "offset_well": "string",
      "min_separation_ft": 0.0,
      "min_separation_md_ft": 0.0,
      "separation_factor": 0.0,
      "traffic_light": "green | yellow | red"
    }
  ],
  "deviation_from_plan": [
    {
      "md_ft": 0.0,
      "inc_delta_deg": 0.0,
      "az_delta_deg": 0.0,
      "position_error_ft": 0.0
    }
  ],
  "anomaly_flags": ["string"],
  "quality_flags": ["string"]
}

Example response

DIRECTIONAL SURVEY ANALYSIS — Wolfcamp B 3H
════════════════════════════════════════════
Total MD:         12,450 ft
Total TVD:         9,820 ft
Max inclination:  90.6°  (at 9,150 ft MD)
Max DLS:           8.2°/100ft  (build section, 5,200 ft MD)
Lateral TI:        4.7 (moderate tortuosity)

SECTION SUMMARY
────────────────
Vertical (0–2,400 ft):     Avg INC 1.2°, Avg DLS 0.2°/100ft
Build (2,400–5,800 ft):    Avg INC 45.2°, Avg DLS 6.8°/100ft
Lateral (5,800–12,450 ft): Avg INC 90.1°, Avg DLS 1.4°/100ft

ANTICOLLISION
──────────────
vs. Wolfcamp B 2H:  Min sep 210 ft (SF 2.8)  GREEN
vs. Wolfcamp B 4H:  Min sep 185 ft (SF 2.4)  GREEN

ANOMALY FLAGS
──────────────
⚠ HIGH_DLS: 8.2°/100ft at 5,200 ft MD — within acceptable build limits but monitor
⚠ SURVEY_GAP: 95 ft gap between stations at 4,850–4,945 ft MD

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ttracx
• Source: ttracx/oil-and-gas-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.