Skip to content
Skills Library
Programming · Review & audit

purpose-sync

/purpose-sync

At the end of a work session, propose updates to a project's purpose tree so each purpose's realized_by matches what the code now does, and flag changes that serve no purpose. Use when wrapping up a session in a project that has purpose-tree.yaml or architecture.yaml, or when asked to sync the purpose tree.

Repository
Homunculus ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/changes.cjs, tests/changes.test.cjs

What it does and when to use it

At the end of a work session, propose updates to a project's purpose tree so each purpose's realized_by matches what the code now does, and flag changes that serve no purpose. Use when wrapping up a session in a project that has purpose-tree.yaml or architecture.yaml, or when asked to sync the purpose tree.

Triggers from the description

s purpose tree so each purpose
Original author description

At the end of a work session, propose updates to a project's purpose tree so each purpose's realized_by matches what the code now does, and flag changes that serve no purpose. Use when wrapping up a session in a project that has purpose-tree.yaml or architecture.yaml, or when asked to sync the purpose tree.

How it works

  1. Steps
  2. Rules
Original SKILL.md headings · 91 lines, 673 words
SKILL.md preview
---
name: purpose-sync
description: At the end of a work session, propose updates to a project's purpose tree so each purpose's realized_by matches what the code now does, and flag changes that serve no purpose. Use when wrapping up a session in a project that has purpose-tree.yaml or architecture.yaml, or when asked to sync the purpose tree.
---

Keep the project's purpose tree in step with its implementations. Uses the
[purpose-tree](../purpose-tree/SKILL.md) method; read it first if you have not.

You touch `realized_by` and `last_synced`. A `purpose` changes only when the human
explicitly accepts a session-end review item (step 2b); never edit one on your own.

## Steps

1. **Collect changes.** Run:

   ```bash
   node <this-skill>/scripts/changes.cjs
   ```

   It prints JSON: the tree file, the base commit (the tree's `last_synced`, or the last
   commit that touched the tree), every changed path since then (committed and not), and
   for each path the node ids whose `realized_by` mentions it. Exit 2 = no tree here: stop
   silently.

   **Too many changes?** If `base_source` is not `last_synced` and there are more than
   50 changes, this is a first sync on an old tree. Do not propose anything. Ask one
   question: "Set the sync baseline to HEAD? (purposes stay as they are; run a tree review
   to catch up)". On yes, do only step 5. Print the summary with `proposed=0`.

2. **Decide proposals.** Work from that JSON, not from memory of the session. Use the
   conversation only to understand *why* something changed.
   - A node's implementation was renamed, moved, or deleted → update its `realized_by`.
   - A node gained a new implementation → add it to that node's `realized_by`.
   - A changed path matches no node (`unmatched`) and is real functionality → propose
     which existing purpose it serves. If none fits, flag it as a **gap**; do not invent
     a purpose.
   - A node now has no implementation left → flag it as a **gap**.
   - Tests, formatting, lockfiles, and docs-only edits are not proposals.

2b. **Session-end review.** Look only at the nodes this session touched and their parents.
   Raise a **review** item when one of these holds:
   - (a) Several implementations of the same purpose were replaced in this session.
   - (b) The node is in `churn`: its `realized_by` already changed 3+ times in 30 days.
     Endless tweaking usually means the purpose is unclear (rabbit-holing).
   - (c) New functionality fits no purpose and looks like a new direction, not a stray file.
   A review item is a question, not an edit: "Is `<id>` still about '<purpose>'?" or "Is
   this a new purpose, or should it not exist?". If the human answers with a new wording,
   apply it; otherwise change nothing. Use the conversation to judge (a) and (c); do not
   go back to older sessions.

3. **If there is nothing to propose: say nothing.** Still do step 5 (advance
   `last_synced`) and print the summary line.

4. **Otherwise ask once.** One numbered list, then one question:

   ```
   Purpose tree — 3 proposals
   1. daily_awareness: realized_by "cron brief" → "scripts/brief.js"
   2. offline_reading: add "app/cache/"
   3. gap: scripts/export.js serves no purpose — which purpose is it for?
   4. review: daily_awareness changed 4 times in 30 days — still "Know what matters before the day starts"?
   Accept all? (or e.g. "reject 2", "3: serves sync_progress")
   ```

   Do not ask follow-up questions. Anything left unanswered counts as rejected.

5. **Apply.** Edit only the accepted `realized_by` entries. Set the top-level
   `last_synced:` to the current `HEAD` commit, even when everything was rejected, so the
   same changes are not proposed again. Then validate:

   ```bash
   node <purpose-tree-skill>/scripts/validate.cjs
   ```

   If validation fails, fix your edit or revert it. Never leave an invalid tree.

6. **Print the summary line** as the last line of your output, exactly:

   ```
   purpose-sync: proposed=<N> accepted=<N> rejected=<N> gaps=<N> reviews=<N>
   ```

   `reviews` counts the review items raised in step 2b.

   This skill stores nothing else. A host that wants to learn from these numbers reads
   this line.

## Rules

- Proposal size matches the node's level: a lower node gets a path; an upper node gets
  at most a short phrase. If you want to change an upper node, raise a review item instead.
- For a tree-wide check (gaps outside this session, stale nodes, failing health checks),
  the human runs the `purpose-review` skill. Do not do that here.
- Commit nothing yourself unless the user asks; the tree edit is part of their work.
Files in this package (3)
  • SKILL.md 5 KB
  • scripts/changes.cjs 4 KB
  • tests/changes.test.cjs 6 KB

Versions

The database has no other skills named purpose-sync.

Database snapshot: 13.11.2026 · package version d9cb3dfa9cb6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100purpose-tree
    The purpose-tree method — how to read, write, and check a project's tree of purposes (why each part exists) separately from its implementations (what currently realizes them). Use when creating, reading, editing, or validating purpose-tree.yaml or architecture.yaml, or when…
  • 100purpose-review
    Build a purpose tree for a project that has none, or review an existing one as a whole — tree-wide gaps, implementations that no longer exist, stale nodes, failing health checks. Use only when the human asks to build, bootstrap, or review the purpose tree (e.g. "build a purpose…
  • 100github-sync
    Review the session's git changes, summarize them for approval, then commit and push to GitHub. Trigger when the user runs /github-sync or says "sync to github", "commit and push", "push this session", "wrap up and push", "save this session to git". For commit-only (no push) or…
  • 86end-session
    Wrap up a work session. Use when the user says they are done, wants to switch tasks, is about to /clear, or asks for a handoff. Verifies checks pass, updates ROADMAP and HANDOFF, and flags uncommitted work.
  • 100yaml-master
    Execute proactive YAML intelligence: automatically activates when working with YAML files. Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.
  • 100yaml-master
    Execute proactive YAML intelligence: automatically activates when working with YAML files. Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.