0xHoneyJar/refreshing-artifacts

Refreshing Artifacts

Re-validate an artifact by routing to the appropriate re-validation skill, then update confidence inputs (NOT the computed score) in frontmatter.

---

Core Principle

Update inputs, not outputs. This skill updates last_validated_at, last_validated_commit, and validation_count in frontmatter. It never stores a computed confidence score — that is always derived by /stale and /drift.

---

Triggers

/refresh {artifact-path}

Examples:

/refresh grimoires/keeper/canvas/xabbu-canvas.md
/refresh grimoires/artisan/taste.md
/refresh grimoires/keeper/reality/profile.md

---

When to Use

• After /stale or /drift shows an artifact needs refreshing
• After significant code changes to validate artifact is still accurate
• Periodically to keep high-value artifacts fresh
• To initialize confidence tracking on artifacts without metadata

---

Workflow

Phase 1: Read Artifact

Parse YAML frontmatter:
  - type (user-canvas, journey, reality, taste, etc.)
  - confidence block (may be missing)

IF confidence block is MISSING:
  Initialize confidence metadata:
    confidence:
      created_at: {now, RFC 3339 UTC}
      last_validated_at: {now}
      last_validated_commit: {git rev-parse HEAD}
      validation_count: 0
      related_paths: {infer from artifact type — see defaults below}

  Write frontmatter and report "Confidence tracking initialized for {path}"
  Skip Phase 2 (no re-validation needed for initialization)
  Proceed to Phase 3

Phase 2: Route to Re-Validation

Based on artifact type, suggest and perform the appropriate re-validation:

IF type == "user-canvas":
  → Suggest: /observe --enrich @{user} --wallet {wallet}
  → Run Score API enrichment to refresh snapshot
  → Update frontmatter score_snapshot if wallet available

IF type == "journey":
  → Suggest: /shape {journey-id}
  → Re-validate journey against current canvases

IF type == "reality":
  → Suggest: /ground {component}
  → Re-extract from current codebase

IF type == "taste" or artifact is grimoires/artisan/taste.md:
  → Suggest: Review taste tokens against current design
  → Validate taste.md still reflects current brand direction

IF type is unknown or unrecognized:
  → Inform user: "Cannot auto-route — please validate manually"
  → Still update confidence inputs in Phase 3

Phase 3: Update Confidence Inputs

Update ONLY these frontmatter fields:

confidence:
  last_validated_at: "{now, RFC 3339 UTC}"
  last_validated_commit: "{git rev-parse HEAD}"
  validation_count: {previous + 1}
  # created_at: UNCHANGED (immutable)
  # related_paths: UNCHANGED (unless user specifies)

Do NOT store a computed current score. Score is always derived.

Phase 4: Emit FeedbackEvent

Emit to grimoires/shared/feedback/events/{YYYY-MM-DD}.jsonl:

{
  "schema_version": 1,
  "id": "fe-{unix_timestamp}-{random4hex}",
  "timestamp": "{RFC 3339 UTC}",
  "domain": "{inferred from artifact type: research for canvas, design for taste, code for reality}",
  "source_pack": "observer",
  "source_skill": "refreshing-artifacts",
  "target": {
    "type": "artifact",
    "selector": "{artifact path relative to repo root}"
  },
  "signal": {
    "direction": "positive",
    "weight": 0.7,
    "specificity": 0.8,
    "content": "Artifact re-validated, confidence inputs updated (validation #{N})",
    "kind": "behavioral"
  },
  "context": {
    "artifact_path": "{artifact path}",
    "confidence_at_time": "{computed score at time of refresh (for reference only)}"
  }
}

Phase 5: Report Output

✓ Artifact refreshed: {artifact-path}

  Validation: #{validation_count}
  Baseline commit: {last_validated_commit[:7]}
  Previous confidence: {computed score before refresh}
  Current confidence:  {computed score after refresh}
  Boost applied:       +{boost value}

  Re-validation: {what was done or suggested}

Next steps:
  → /stale (check overall artifact health)
  → /drift {path} (see detailed drift report)

---

Default Related Paths

When initializing confidence for the first time, infer related_paths from artifact type:

| Artifact Type | Default related_paths | |---------------|----------------------| | user-canvas | ["lib/score-api/**", "grimoires/keeper/canvas/"] | | journey | ["grimoires/keeper/canvas/", "grimoires/keeper/journeys/"] | | reality | ["src/", "lib/"] | | taste | ["grimoires/artisan/", "src/components/"] | | unknown | [] (empty — user should configure) |

---

Error Handling

| Error | Resolution | |-------|------------| | Artifact not found | Error with path suggestion | | Git not available | Use current timestamp, skip commit SHA, warn | | Frontmatter parse error | Attempt repair, or error with backup suggestion | | Re-validation skill not available | Update inputs anyway, note in report | | No wallet for canvas enrichment | Skip enrichment, update inputs only |

---

Integration Points

• Reads: Artifact frontmatter, git state
• Writes: Artifact frontmatter (confidence inputs only), FeedbackEvent
• Routes to: /observe --enrich, /shape, /ground (depending on type)
• Consumed by: /stale and /drift (after refresh, scores improve)

---

Validation

• [ ] Reads confidence frontmatter correctly
• [ ] Initializes confidence when missing
• [ ] Routes to correct re-validation per type
• [ ] Updates ONLY inputs (last_validated_at, last_validated_commit, validation_count)
• [ ] Does NOT store computed score
• [ ] Emits FeedbackEvent
• [ ] Report shows before/after confidence
• [ ] Default related_paths are reasonable per type