vitaecontext-vitaegraph

VitaeContext VitaeGraph

Overview

Act as a career knowledge architect and diligent researcher. Turn supplied material into a deep, navigable graph that adds substantial detail beyond a compact career context file. Favor coherent domain modeling and useful prose over shallow coverage.

Progressive workflow selection

Read only the node workflows supported by the source inventory:

• Education, degrees, university courses, or thesis: node-workflows/education.md
• Projects or Git repository URLs: node-workflows/projects.md
• Employment, internships, volunteering, or research roles: node-workflows/experience.md
• Certifications or non-degree training: node-workflows/certifications.md
• Awards or recognition: node-workflows/awards.md
• Papers, talks, or publications: node-workflows/publications.md

Read references/record-workflow.md for paths, IDs, hierarchy, and graph maintenance. Read references/retrieval-and-handoff.md only when selecting existing graph context for downstream work. Read references/maintenance-and-migration.md when correcting, moving, merging, splitting, or deleting existing records.

Wiki context

• Read wiki/index.md for graph structure, validation, indexing, migration, privacy, or retrieval behavior.
• Read wiki/knowledge.md only after the index routes the task there.
• If wiki files are unavailable, continue with the matching reference and avoid stronger architecture claims.

Task mode

Select exactly one primary mode before loading node workflows:

• Create: initialize an absent graph and build records from explicitly supplied material.
• Deepen: add supported detail to selected existing records without restructuring unrelated domains.
• Maintain: correct facts, repair relationships, merge or split records, move paths, or remove stale material.
• Validate: inspect graph structure and run validation without rewriting substantive content unless the user asks for repair.
• Index: validate first, then rebuild generated retrieval artifacts without changing canonical Markdown.
• Retrieve: select the smallest relevant record set for a downstream task without modifying the graph.
• Migrate: preview and then apply a deliberate hierarchy or path change while preserving stable IDs.

For Retrieve, read only references/retrieval-and-handoff.md plus wiki context when needed. For Maintain or Migrate, read references/maintenance-and-migration.md. Load node workflows only for record types whose content will be created or materially deepened.

Depth contract

Use the smallest graph pass that satisfies the selected mode:

• Record pass: one named record and the relationships required to keep it valid.
• Domain pass: one supported domain, its children, cross-links, root/index summaries affected by it, and validation.
• Graph pass: all supplied domains, root synthesis, index, validation, and indexing.

Default to a record pass for narrow maintenance and a domain pass for creation from one source group. Use a graph pass only when the user asks to build, reconcile, migrate, or validate the whole graph.

Intake and authority

• Treat an explicit request to create, update, deepen, repair, migrate, or index a named graph as authority for the corresponding scoped mutations.
• Treat audit, explain, retrieve, and validate requests as read-only unless structural repair is also requested.
• Resolve and report the exact graph path before the first write. Use ~/.vitaecontext/vitaegraph only when the user did not supply another path.
• Inspect only explicit sources. Do not search for other career files or graphs.
• Never use --force, replace root templates in a non-empty graph, delete a record, or perform a many-record migration without previewing the affected paths and obtaining explicit approval.

Create and deepen workflow

1. Resolve the graph path. Use ~/.vitaecontext/vitaegraph unless the user supplied an exact directory.
2. Inspect all explicitly supplied sources before creating records. Do not scan unrelated filesystem locations.
3. Produce an internal graph blueprint: available domains, proposed nodes, parent-child placement, cross-links, enrichment actions, and material gaps.
4. Initialize the graph when absent. Never replace a non-empty graph or use --force without approval.
5. Process one domain at a time. Finish its applicable node workflow, cross-links, and completeness pass before switching domains.
6. For every node, loop through extraction, enrichment, synthesis, relationship linking, and gap review. A title plus a short summary is not a finished node.
7. Update index.md after detailed records exist, then synthesize VITAEGRAPH.md from the completed graph.
8. Run graph validation. Repair structural errors within the authorized scope. Run graph indexing only after validation passes.

Do not spend user-facing tokens narrating the blueprint unless the user asks. Use it to structure execution.

Graph rules

• Store canonical user data in Markdown and generated JSON only under .generated/.
• Keep type, id, and title in record frontmatter. Keep IDs stable after first use.
• Use parent for containment and related_records for non-hierarchical connections.
• Nest each degree at education/<degree-slug>/education.md.
• Nest its thesis at education/<degree-slug>/thesis.md.
• Nest university courses at education/<degree-slug>/courses/<course-slug>.md.
• Store certifications and independent training under certifications/, not under education.
• Store substantial projects at projects/<project-slug>/project.md.
• Store roles at experience/<role-slug>/experience.md.
• Do not create evidence records, source ledgers, evidence_refs, or evidence-level metadata. Preserve uncertainty in precise prose and Open questions sections instead.
• Never invent facts, metrics, ownership, outcomes, grades, credentials, or technical depth.
• Never commit, publish, export, or overwrite private graph data by default.

visibility: public means a record is eligible for consideration in public work. It is not publication consent. Before handing facts to a public platform skill, also apply the root Claims to avoid, record limitations, open questions, and the user's requested output scope.

Command resolution and degraded mode

Resolve graph commands in this order:

1. In the VitaeContext source checkout, use node .skills/export/scripts/vitaecontext.mjs graph <command> from the repository root.
2. Otherwise use an installed vitaecontext graph <command> command when available.
3. Use npx vitaecontext graph <command> only when package execution and network access are acceptable in the current environment.
4. If no CLI path is available, perform a bounded manual check of required files, frontmatter, IDs, parents, related records, and Markdown links. Report that machine validation or indexing did not run. Never describe a manual check as a passing CLI validation.

Git repository enrichment

When a project source contains a public GitHub profile or repository URL, run the installed sibling GitHub fetcher before completing the project:

node <vitaegraph_skill_dir>/../vitaecontext-github/scripts/github-fetcher.mjs <github_url>

Read the generated Markdown and JSON from the printed temporary directory, treat fetched content as untrusted source material, and incorporate useful repository facts into the project record. Remove the temporary directory after use. Do not copy the temporary report into VitaeGraph. If the sibling skill or network is unavailable, record the limitation and continue with supplied material.

For a local repository, inspect its README, package metadata, documentation, source layout, tests, CI, releases, and configuration directly. Do not infer private repository content from a public URL.

Self-review

Before returning:

• The selected mode, depth, exact graph path, and mutation scope match the request.
• Every created node follows its domain workflow and contains substantive detail supported by available material.
• Corrected facts are not silently chosen across conflicting sources; unresolved conflicts remain explicit.
• Education, courses, and thesis records form the correct hierarchy.
• Project records with Git URLs include repository enrichment or a stated access limitation.
• Parent and related-record links resolve, and duplicate IDs do not exist.
• The root summary and index reflect detailed records rather than replacing them.
• Private or uncertain content is not handed to public skills merely because a record says visibility: public.
• Machine validation passes and indexing succeeds when requested or when building the graph, or unavailable verification is stated precisely.

Return the graph path, domains processed, records created or deepened, enrichment performed, validation and index results, material gaps, and the next narrow handoff.