Skip to content

docs(skills): add graphile-postgis skill for @spatialRelation + RelationSpatial#999

Merged
pyramation merged 2 commits intomainfrom
devin/1776484752-postgis-spatial-skills
Apr 18, 2026
Merged

docs(skills): add graphile-postgis skill for @spatialRelation + RelationSpatial#999
pyramation merged 2 commits intomainfrom
devin/1776484752-postgis-spatial-skills

Conversation

@pyramation
Copy link
Copy Markdown
Contributor

Summary

Adds a new .agents/skills/graphile-postgis/SKILL.md so future Devin sessions (particularly agentic-DB sessions, which were the original motivator for the PostGIS work) reach for the right primitive when a task involves spatial queries.

The skill covers:

  • When to use it — triggers like "find clinics in a county", "client is pulling GeoJSON to filter in JS", "about to write a per-pair helper SQL function".
  • Tag grammar for @spatialRelation + the 8-operator reference table (including the st_dwithin parametric case).
  • Blueprint shape for the new RelationSpatial node (one-direction-per-tag, idempotent, metadata-only).
  • ORM where: usagesome / every / none semantics, parametric distance:, and composition with and/or/not.
  • Self-relations (single vs composite PK exclusion, distance: 0 corner case).
  • GIST indexing and the @spatialRelationSkipIndexCheck escape hatch.
  • Debugging checklist seeded with the concrete failures from shipping this feature (column reference "name" is ambiguous, bare vs metaschema-modules:-prefixed pgpm.plan refs, smart-tag clobber, some: {} semantics, SRID vs meters).
  • Scope guardrails listing common wrong turns (custom resolver taking a polygon, per-pair helper functions, mixing codecs, using in orderBy).
  • Pointers to plugin source, README, blueprint node, and the E2E/unit test suites.

Also adds a one-line cross-link to the new skill from constructive-monorepo-setup/SKILL.md under the "Graphile Plugin Development" section so it's discoverable from the monorepo entry-point skill.

No code changes. Plugin README already contains the full reference (from #994) — this skill is deliberately a shorter, task-oriented summary that points at the README for deep details.

Review & Testing Checklist for Human

  • Content accuracy — skim the operator table and tag grammar against graphile/graphile-postgis/README.md and graphql/node-type-registry/src/relation/relation-spatial.ts to confirm the skill doesn't drift from the source of truth.
  • Relative link correctness — the skill references ../../../graphile/graphile-postgis/... and ../../../graphql/node-type-registry/... (three levels up from .agents/skills/graphile-postgis/). Click through once to verify GitHub renders them.
  • Tone / scope for an agent consumer — this is written for Devin sessions, not humans. Flag anything that reads more like product marketing than actionable instructions.

Notes

  • The skill deliberately repeats a subset of the README rather than linking out exclusively — agent sessions often need self-contained guidance without a second fetch.
  • The "Debugging checklist" symptoms are lifted from real failures encountered while shipping constructive-io/constructive-db#844 (parameter ambiguity) and the pgpm cross-module reference issue in the same PR, so they'll appear verbatim in future sessions.
  • Phase C (agentic-DB prompt update) is a follow-up that now has a concrete URL to cite.

Link to Devin session: https://app.devin.ai/sessions/c5eeee65a3c546c4ac6753bb05fa03e0
Requested by: @pyramation

@devin-ai-integration
Copy link
Copy Markdown
Contributor

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@pyramation pyramation merged commit 7bef6a6 into main Apr 18, 2026
51 checks passed
@pyramation pyramation deleted the devin/1776484752-postgis-spatial-skills branch April 18, 2026 04:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant