Update to GeoAI Skills

{
  "name": "geo-deep-learning",
  "description": "Invoke before recommending, training, or auditing a neural method for geospatial imagery, including vision transformers, U-Net/DeepLab/SegFormer, object detection, pixel classification, building/road extraction, and EO foundation-model fine-tuning. Also invoke for neural chip-split validity, IoU/accuracy claims, augmentation, imbalanced losses, spatial validation, or sliding-window inference. Use remote-sensing-analysis for non-neural methods and change-detection when temporal change is the deliverable.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 224
    },
    {
      "relative_path": "references/authoritative-sources.md",
      "size_in_bytes": 792
    }
  ],
  "skill_md_contents": "---\nname: geo-deep-learning\ndescription: >-\n  Invoke before recommending, training, or auditing a neural method for\n  geospatial imagery, including vision transformers, U-Net/DeepLab/SegFormer,\n  object detection, pixel classification, building/road extraction, and EO\n  foundation-model fine-tuning. Also invoke for neural chip-split validity,\n  IoU/accuracy claims, augmentation, imbalanced losses, spatial validation,\n  or sliding-window inference. Use remote-sensing-analysis for non-neural\n  methods and change-detection when temporal change is the deliverable.\nlicense: MIT\nmetadata:\n  author: Muhammed Enes Duran\n---\n\n# Geospatial Deep Learning\n\nPurpose: deep learning on Earth observation with the two failure modes that\ndominate this field designed out from the start: **spatial leakage**\n(inflated metrics from nearby train/test pixels) and **georeferencing loss**\n(predictions that no longer align with the map).\n\n## Characterise the label set before naming an architecture\n\nArchitecture advice given without knowing the label set is guesswork. Before\nrecommending U-Net versus a foundation model versus a non-deep baseline, state\nor ask for:\n\n- **Label count and labelled area** — polygons alone say nothing; 40 polygons\n  covering 2 ha and 40 covering 2 000 km² are different problems.\n- **Geographic spread** — are the labels clustered in one scene, one season and\n  one sensor, or distributed across the deployment domain? Clustered labels cap\n  what any model can generalise to, and they decide whether a geographically\n  independent validation split is even constructible.\n- **Class balance and minority-class pixel fraction**, so loss and sampling\n  choices are grounded rather than assumed.\n- **Deployment geography** — where predictions will be made, relative to where\n  the labels are.\n\nDo not answer \"fine-tune a large model or use a simpler approach\" before these\nare known. When the user has not supplied them, ask and give the provisional\nrecommendation *conditioned on* the answers (\"if the 40 polygons sit in one\nscene, then …; if they span the region, then …\"), never a single unconditional\nrecommendation.\n\n## Problem framing first\n\n| Task | Head/architecture default | Metric |\n|---|---|---|\n| Pixel-wise classes (land cover) | U-Net / DeepLabv3+ (pretrained encoder) | mIoU, per-class IoU |\n| Binary extraction (buildings, water, roads) | U-Net + Dice/CE hybrid | IoU, F1; boundary F1 for roads |\n| Object detection (vehicles, ships, trees) | YOLO-family / Faster R-CNN, rotated boxes if oriented | mAP@50 |\n| Scene classification | Fine-tuned CNN/ViT | F1 (macro) |\n| Regression (height, biomass, density) | U-Net with regression head | RMSE/MAE + spatial residual map |\n\nBefore any deep model: run a cheap baseline (random forest on bands+indices,\nor thresholded index). If the DL model can't beat it clearly, the problem is\ndata, not architecture. `segmentation-models-pytorch` and `torchgeo` cover\nmost needs — don't hand-build architectures without a reason.\n\n## Chipping (dataset construction)\n\n- Chip size: 256–512 px; stride < chip size only for training (overlap\n  augments), never let overlapping chips straddle the train/val boundary.\n- **Preserve georeferencing**: store each chip's transform/bounds (torchgeo\n  datasets or a sidecar index in GeoParquet). A prediction you can't put\n  back on the map is worthless.\n- Keep chips in the native data range; normalize with **dataset-computed**\n  per-band statistics (ImageNet stats only for 3-band RGB with a pretrained\n  encoder, and say so).\n- Class imbalance is the norm (buildings ≈ 2-5% of pixels). Log per-chip\n  class fractions; oversample positive-containing chips rather than\n  distorting the loss beyond recognition.\n\n## Split policy — the non-negotiable\n\nSplit by **geographic block or scene**, never by random chip. Adjacent\nchips are near-duplicates; random splits produce beautiful, fake validation\ncurves. Follow the canonical protocol:\n`ml-experiment-standards` → `references/spatial-cv-protocol.md`.\nFor generalization claims across regions, hold out an entire region.\n\n## Training defaults\n\n- Loss: Dice + CE (segmentation, imbalanced); plain CE when balanced; Focal\n  only after comparing — it's not a free win.\n- Augmentation: flips/rot90 are safe for nadir imagery; be careful with\n  color jitter on multispectral (it breaks radiometric meaning — prefer\n  band dropout or slight scaling); never augment in ways that violate the\n  physics.\n- Encoder pretrained; multispectral input → inflate/replace first conv, or\n  use an EO foundation model checkpoint (Prithvi, SatMAE, Clay) when bands\n  match.\n- Early stopping on val mIoU (patience 10-15); cosine or plateau LR\n  schedule; AMP on by default.\n- Log config + metrics + git hash per run — see `ml-experiment-standards`.\n\n## Inference on large scenes\n\nSliding window with overlap (25-50%) and blending (feather/gaussian or\ncenter-crop stitching) to kill tile-edge artifacts. Then:\n\n```python\nimport rasterio\n\nwith rasterio.open(scene_path) as src:\n    profile = src.profile\nprofile.update(count=1, dtype=\"uint8\", nodata=255, compress=\"deflate\")\nwith rasterio.open(out_path, \"w\", **profile) as dst:\n    dst.write(mask.astype(\"uint8\"), 1)  # same transform/CRS as the scene\n```\n\nPost-process: sieve tiny blobs (min mapping unit), optionally regularize\nbuilding polygons, and vectorize (`rasterio.features.shapes`) for GIS\ndelivery. Report metrics AFTER post-processing too — that's what the user\nships.\n\n## Verification protocol\n\n1. Metrics table: per-class IoU/F1 with CI across seeds or folds.\n2. **Error map**: prediction vs reference overlaid on imagery for 3+\n   representative areas including a known-hard one.\n3. Sanity inference on an out-of-distribution patch (different season/\n   region) with an honest note on degradation.\n4. Alignment check: overlay predictions on the source scene in a GIS at\n   two zoom levels — catches transform bugs instantly.\n\n## Pitfalls checklist\n\n- Random chip split → leaked, unreproducible \"SOTA\".\n- Normalizing test data with train-time stats not saved → skewed inference.\n- Losing the geotransform in NumPy-land; writing predictions with default\n  north-up transform.\n- Tile-edge seams from no-overlap inference.\n- uint16 imagery fed to a float pipeline without scaling → dead gradients.\n- Accuracy reported on chip level while the product is a stitched map.\n\n## Execution contract\n\n- **Workflow:** frame target and unit of prediction; build chips and labels; create spatial splits; train against a baseline; run overlap-aware inference; validate the stitched product.\n- **Decision rules:** use deep learning only when label volume, spatial texture, compute, and expected uplift justify it; otherwise prefer a simpler remote-sensing or ML workflow.\n- **Verification protocol:** report spatial holdout metrics across seeds or folds, inspect error maps and hard areas, test geographic transfer, and check output georeferencing.\n- **Failure modes:** invalidate results for leaked chips, label misalignment, train/inference normalization drift, tile seams, or metrics computed at the wrong product unit.\n- **Deliverables:** model and configuration, split manifest, preprocessing contract, metrics with uncertainty, georeferenced predictions, error maps, and model card limitations.\n- **Source freshness:** consult [the authoritative source registry](references/authoritative-sources.md) before selecting framework APIs, datasets, or weights and record the checked date.\n"
}