| name | gmeow-developer-start-issue |
| description | Guides the agent in properly framing and beginning work on a GitHub issue in the GMEOW repository. Use when a new issue has been assigned, picked up, or needs analysis before implementation. |
GMEOW Developer — Starting a GitHub Issue
This skill governs how an agent transitions from "issue assigned" to "implementation ready" in the GMEOW ontology repository. It is a behavioural contract: follow it in order, do not skip steps, and cite the CONSTITUTION.md principles that govern every decision.
Meta-rule: If any step below conflicts with a Constitution principle, the principle wins. Either revise the step or amend the Constitution in the same pull request — never silently override.
1. Before You Start — Read the Constitution
Every issue is a design decision. Before touching code, mappings, or ontology modules:
- Open
CONSTITUTION.md and read the twelve principles.
- Identify which principles are most relevant to the issue at hand.
- Cite the principle(s) by number (e.g. "Principle 4", "Principles 5 & 9") in your branch plan, commit messages, and eventual PR description.
- If the issue appears to conflict with a principle, flag it immediately in the issue thread or PR description. A design that conflicts with a principle must either:
- be revised to comply, or
- ship together with an explicit amendment to
CONSTITUTION.md.
Never silently override a principle. Principle numbers are stable identifiers across history.
2. Plan Mode & Issue Transparency
For any non-trivial issue — new features, architectural changes, multi-file refactors, or ontology additions — enter plan mode before writing implementation code.
- ALL COMMENTS MUST BE READ You must read all the github issue comments using the gh cli and JSON format.
- Write the plan to the active plan file (the agent's designated plan path).
- Get approval via
ExitPlanMode before proceeding.
- Post the approved plan as a comment on the GitHub issue.
Why: The approved plan is the design contract. Posting it to the issue creates a transparent, time-stamped record that reviewers and future maintainers can reference. It prevents drift between "what was agreed" and "what was implemented."
When posting, include:
- A brief summary of the approach
- The key Constitution principle(s) that govern the design
- Any research findings (existing ontologies checked, partial matches found, etc.)
- A link to or verbatim paste of the plan content
If the plan is amended during implementation, post a follow-up comment explaining the delta and why it was necessary.
3. Worktree Discipline
GMEOW uses git worktrees for isolation. The repository root contains a .worktrees/ directory (already gitignored). Follow this lifecycle exactly.
3.1 Create the worktree
git fetch origin
issue_slug="issue-${ISSUE_NUMBER}-$(echo ${ISSUE_TITLE} | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/-*$//')"
git worktree add ".worktrees/${issue_slug}" -b "${issue_slug}"
cd ".worktrees/${issue_slug}"
- Branch name should be descriptive and include the issue number.
- Worktree directory lives under
.worktrees/ in the repo root.
3.2 Work all the way to the PR
Finish the entire plan, perform any checking required, then commit with a comprehensive commit message and PR. Do not stop until you have PR'd the branch.
3.3 Keep the worktree alive until merge
The worktree and branch must survive until the associated pull request is merged into main. Do not delete them after the first commit, after opening the PR, or after initial review. They are the isolated workspace for the entire issue lifecycle.
3.4 After merge — clean up
Once the PR is merged and main is green:
git worktree remove ".worktrees/${issue_slug}"
git branch -D "${issue_slug}"
git pull origin main
- Remove the worktree first, then delete the branch.
- Pull an updated
main so the next issue starts from the latest canonical source.
4. Ontological Orientation — Projections, Logic, and Linkage
GMEOW is reasoning-centric, OWL 2 DL, and upper-ontology-grounded. Every issue must be analysed through these three lenses before implementation begins.
4.1 Projections (the boundary layer)
- If the issue touches cross-vocabulary alignment, the canonical source is
mapping-dsl/ — never hand-edit mappings/*.sssom.tsv, projections/*.edoal.ttl, or queries/projections/*.rq.
- A projection is a deliberately lossy, directional downcast. It lives at the boundary, not in the core.
- Before adding a new projection, ask: does this exist already in SSSOM, EDOAL, FnO, or SPARQL form? If not, plan the mapping-dsl source that generates it (Principle 4).
4.2 Logic (the reasoned core)
- Every new class or property must be grounded under a gUFO category and stay inside OWL 2 DL.
- Every definition must carry
rdfs:label and skos:definition.
- Before implementation, predict whether the native reasoner (
make reason) will stay green. If you are unsure, run a quick reason check on a spike branch first.
- If the issue involves statement-level metadata (provenance, confidence, temporal scope), the canonical source is
statement-dsl/ in RDF 1.2 / RDF* shape — the OWL axiom-annotation form is a generated downcast (Principles 2–3).
4.3 Linkage (maximal bridging by reference)
- Principle 5: mint exactly one canonical term per concept and align it to every relevant surface vocabulary by reference — never rewrite anyone else's data.
- Before minting a new term, search existing mappings and external vocabularies. The goal is maximal superset, maximal bridging.
- Link by IRI freely; never copy axioms from a reference-only or copyleft source.
5. Research First, Mint Second
Researching existing ontologies, vocabularies, or standards that could augment or align with current work is ALWAYS a good idea.
Before proposing a new GMEOW term or mapping, investigate:
- Surface vocabularies: schema.org, FOAF, vCard, GeoSPARQL, GEDCOM, DOAP, PROV-O, ORG, SKOS, DCTerms
- Foundational / upper ontologies: gUFO, BFO 2020, DOLCE
- Domain ontologies: FIBO (finance), OWL-Time (temporal), QUDT / OM (measurement), Lexvo (language)
- Hubs & knowledge bases: Wikidata (QIDs for entities, PIDs for properties)
Document your findings in the issue or PR — even if the conclusion is "nothing suitable exists; minting new." This audit trail is valuable for reviewers and future maintainers.
Tip: If you find a partial match, model the GMEOW term correctly and bridge to the weaker form by reference (Principle 1: SOTA by being SOTA — model what should have been written, never inherit the weakness).
6. Git Workflow & Rebase Hygiene
6.1 Stay current with main
If main has moved ahead of your feature branch, rebase carefully before committing new work or before pushing:
git fetch origin
git rebase origin/main
- Prefer
git rebase main over merge commits. GMEOW values linear, reviewable history.
- Resolve conflicts in the worktree, run the full gate (
make check), and only then continue the rebase.
6.2 Force-push only when safe
After a rebase, force-push is acceptable only on a personal feature branch that no one else is working on:
git push --force-with-lease origin "${issue_slug}"
6.3 Conventional Commits
Use Conventional Commits:
feat: — new functionality or ontology termsfix: — bug fixesdocs: — documentation-only changesrefactor: — internal restructuring without behaviour changetest: — test additions or updateschore: — maintenance work
Cite Constitution principle numbers in commit messages where relevant. Example:
feat: add Location reference-frame Profile and coarsenTo projection
Principle 11 (frame-relativity) + Principle 4 (canonical source):
- Canonical term authored in ontology/modules/location.ttl
- Projection authored in mapping-dsl/projections/geosparql.ttl
- Coarsening function added to projections/transforms.fno.ttl
7. Issue-to-PR Checklist
Before declaring an issue "ready to implement" or opening a pull request, verify:
See Also
