@ghostpaw/affinity 0.2.2 → 0.3.0

package/skills/affinity/references/manage-recurring-dates-and-reminders.md

@@ -0,0 +1,49 @@
+# Manage Recurring Dates And Reminders
+
+Primary tools:
+- `manage_date_anchor`
+- `review_affinity`
+- `inspect_affinity_item`
+
+Goal:
+- Materialize recurring important dates into a durable reminder surface that later review and relationship maintenance can trust.
+
+When to use:
+- A date recurs yearly and matters to a contact or link.
+- You want reminders for birthdays, anniversaries, renewals, memorials, or other yearly anchors.
+
+When not to use:
+- The date is a one-off event.
+- The fact is a preference or metadata note rather than a recurring anchor.
+
+Step-by-step sequence:
+1. Confirm the target contact or link first.
+2. Use `manage_date_anchor` with `action: "add"` and the right recurrence kind.
+3. Keep the summary operator-friendly so future reminders are immediately understandable.
+4. Use `review_affinity` with the upcoming-dates view and an explicit horizon during regular review work.
+5. Revise anchors when recurrence details change.
+6. Remove anchors when the reminder surface should no longer treat the date as active.
+
+Validation checks:
+- The anchor appears in upcoming-date review when it falls within the chosen horizon.
+- Duplicate anchors are not silently piling up.
+- The summary and significance are still meaningful for later action.
+
+Pitfalls:
+- Do not store important recurring dates only as loose attributes.
+- Do not create duplicate yearly anchors for the same target and meaning.
+- Do not use recurring anchors for commitments; those belong in the commitment flow.
+
+Tips and tricks:
+- Tune horizons by workflow: short for weekly review, longer for quarterly planning.
+- Use significance to help order upcoming-date review meaningfully.
+- Link-level anchors are valuable when the date belongs to a relationship rather than one person.
+
+Tool calls to prefer:
+- `manage_date_anchor` for add, revise, and remove
+- `review_affinity` with the upcoming-dates view
+- `inspect_affinity_item` when you need exact context on the target
+
+Related skills:
+- `manage-promises-and-agreements`
+- `review-radar-progression-and-graph`

package/skills/affinity/references/model-structure-orgs-and-households.md

@@ -0,0 +1,50 @@
+# Model Structure, Orgs, And Households
+
+Primary tools:
+- `manage_contact`
+- `manage_relationship`
+- `inspect_affinity_item`
+- `review_affinity`
+
+Goal:
+- Capture the stable factual skeleton of the world: who belongs where, who reports to whom, and what entities are structurally connected.
+
+When to use:
+- You need to represent employment, family structure, team membership, households, or service affiliation.
+- The fact should exist even if no emotional or operational relationship score is implied.
+
+When not to use:
+- You want to express how strong, strained, warm, or active a relationship feels.
+- You are recording something that happened in time.
+
+Step-by-step sequence:
+1. Create or locate the entities involved.
+2. Decide whether the fact is structural rather than relational. If the answer survives even with zero interaction history, it is usually structural.
+3. Use `manage_relationship` with `action: "set_structural_tie"` to record the factual tie.
+4. Include a role when the role clarifies the structure, such as job title or household role.
+5. Inspect relevant profiles or review lists after large structural batches to confirm the world model is clean.
+6. Remove or replace outdated ties when the world changes, such as a job move or team change.
+
+Validation checks:
+- The structural tie is visible and stable.
+- No fake progression fields were introduced just to represent a factual tie.
+- The chart and review surfaces now reflect the world structure you expect.
+
+Pitfalls:
+- Do not use structural ties to stand in for closeness, trust, or cadence.
+- Do not seed social links just because a structural tie exists; only do that if a live relational track also matters.
+- Do not leave outdated structural ties hanging after the factual world changes.
+
+Tips and tricks:
+- Structural and relational links can coexist. Use both when both truths matter.
+- Groups, households, companies, teams, and services often deserve their own contacts.
+- If you are unsure, ask whether the statement is about belonging or about lived relationship quality.
+
+Tool calls to prefer:
+- `manage_relationship` with `set_structural_tie`
+- `inspect_affinity_item` to verify exact targets
+- `review_affinity` for broader structural review
+
+Related skills:
+- `identify-and-locate-contacts`
+- `record-direct-evidence-well`

package/skills/affinity/references/reconcile-duplicates-and-merge-safely.md

@@ -0,0 +1,49 @@
+# Reconcile Duplicates And Merge Safely
+
+Primary tools:
+- `review_affinity`
+- `inspect_affinity_item`
+- `merge_contacts`
+
+Goal:
+- Collapse true duplicates without losing lineage, identities, participants, or relationship truth.
+
+When to use:
+- Duplicate-candidate review surfaces indicate a likely duplicate.
+- A harness or operator has strong evidence that two contacts are the same real entity.
+
+When not to use:
+- The match is still speculative and unresolved.
+- The real need is just better identities or labels rather than an actual merge.
+
+Step-by-step sequence:
+1. Start with `review_affinity` on the duplicate-candidate view.
+2. Inspect both candidate contacts before merging.
+3. Confirm the winner explicitly rather than letting recency or convenience decide by accident.
+4. Use `merge_contacts` only when the identity and history picture is clear.
+5. Inspect the surviving contact after the merge to confirm the merged state looks right.
+6. Review merge history when you need lineage confirmation later.
+
+Validation checks:
+- The surviving contact now contains the expected identities and visible history.
+- The loser is no longer treated as a live normal contact.
+- The merge reason is still understandable when reviewed later.
+
+Pitfalls:
+- Do not merge on a weak fuzzy-name match alone.
+- Do not skip inspection of both sides before merging.
+- Do not assume merges are easy to conceptually undo just because the system preserves lineage.
+
+Tips and tricks:
+- Prefer a winner that already carries the stronger routing identity and richer history unless another reason dominates.
+- If the system is uncertain, clarify first instead of forcing a merge.
+- Review merge history after sensitive merges to confirm the lineage chain is clean.
+
+Tool calls to prefer:
+- `review_affinity` for duplicate-candidate discovery and merge-history review
+- `inspect_affinity_item` for both candidate contacts
+- `merge_contacts` only after confirmation
+
+Related skills:
+- `identify-and-locate-contacts`
+- `import-history-without-faking-evidence`

package/skills/affinity/references/record-direct-evidence-well.md

@@ -0,0 +1,52 @@
+# Record Direct Evidence Well
+
+Primary tools:
+- `record_event`
+- `inspect_affinity_item`
+- `review_affinity`
+- `manage_relationship`
+
+Goal:
+- Capture what really happened between the owner and other contacts so Affinity can derive progression, trust, cadence, and moments cleanly.
+
+When to use:
+- A conversation, activity, support exchange, conflict, correction, milestone, or direct operational interaction just happened.
+- You want future radar, progression, journal, and chart views to reflect the event truthfully.
+
+When not to use:
+- You are importing pre-system history.
+- You only observed third parties and were not directly part of the relationship evidence.
+
+Step-by-step sequence:
+1. Confirm the participants first. Use exact contacts whenever possible.
+2. Use `record_event` with the smallest honest event family: `interaction` for ordinary direct evidence, `milestone` when the event is truly milestone-shaped, or another event family only when it better matches reality.
+3. Set significance conservatively. Use high significance only when the event genuinely changed the relationship.
+4. Let the system auto-create owner-facing links when appropriate instead of manually seeding a link just because a direct event happened.
+5. Review the receipt or inspect the resulting profile when you need to understand the effect.
+6. Use `review_affinity` on journal, timeline, moments, or readiness views when you need context after a sequence of events.
+
+Validation checks:
+- The right contacts were involved.
+- The event family matches what really happened.
+- The resulting mechanics feel plausible when reviewed.
+
+Pitfalls:
+- Do not inflate significance to force a rank-up.
+- Do not turn ordinary direct evidence into a milestone just to get a dramatic moment.
+- Do not use bond text as evidence. If the bond changed but no event happened, revise the bond separately.
+- Do not guess through ambiguity; clarify the target first.
+
+Tips and tricks:
+- Conflict and correction are both first-class direct evidence. Use them honestly rather than hiding them inside generic summaries.
+- Multi-participant owner events can refresh multiple links at once. That is a feature, not a bug.
+- If you need to label the current narrative reading without changing mechanics, use `manage_relationship` with `revise_bond` after the evidence is recorded.
+
+Tool calls to prefer:
+- `record_event` for the evidence itself
+- `inspect_affinity_item` for exact read-back
+- `review_affinity` for journals, timelines, moments, and readiness
+- `manage_relationship` only for bond interpretation after the fact
+
+Related skills:
+- `record-observations-and-referrals`
+- `review-radar-progression-and-graph`

package/skills/affinity/references/record-observations-and-referrals.md

@@ -0,0 +1,48 @@
+# Record Observations And Referrals
+
+Primary tools:
+- `record_event`
+- `review_affinity`
+- `inspect_affinity_item`
+
+Goal:
+- Add truthful third-party graph information while keeping observational evidence weaker than direct relationship evidence.
+
+When to use:
+- You learned that two people know each other, one person referred another, or you observed a third-party relationship pattern.
+- You want the graph to reflect world truth without pretending you had the direct interaction yourself.
+
+When not to use:
+- The owner directly participated in the event and should record direct evidence instead.
+- You merely suspect a relationship with no strong enough fact to justify recording it.
+
+Step-by-step sequence:
+1. Confirm the third-party contacts you are referring to.
+2. Use `record_event` with `kind: "observation"` when the truth is observational rather than direct.
+3. Keep significance modest unless the observed fact is genuinely consequential.
+4. After recording, use `review_affinity` to inspect observed-link or graph views and verify the resulting topology.
+5. If later direct evidence exists, record that separately rather than expecting the observation to do all the work.
+
+Validation checks:
+- The graph now reflects the third-party fact you meant to capture.
+- Observed links stay appropriately weaker than direct links.
+- No accidental owner-facing intimacy was invented.
+
+Pitfalls:
+- Do not use observations to fake deep trust or rank.
+- Do not create a clique from vague group knowledge when the system only has justified pairwise facts.
+- Do not promote a rumor to structure or direct evidence without better confirmation.
+
+Tips and tricks:
+- Referral chains are excellent observational facts because they help later review and graph interpretation.
+- Use chart and observed-link review views together after batches of observation work.
+- Observations are often better than silence, but they should remain humble.
+
+Tool calls to prefer:
+- `record_event` with `observation`
+- `review_affinity` with observed-link and graph views
+- `inspect_affinity_item` if you need exact follow-up on one target
+
+Related skills:
+- `record-direct-evidence-well`
+- `review-radar-progression-and-graph`

package/skills/affinity/references/review-radar-progression-and-graph.md

@@ -0,0 +1,48 @@
+# Review Radar, Progression, And Graph
+
+Primary tools:
+- `review_affinity`
+- `inspect_affinity_item`
+
+Goal:
+- Turn review surfaces into a disciplined operating loop for outreach, prioritization, and graph understanding.
+
+When to use:
+- You need a daily or weekly maintenance pass.
+- You want to know who is drifting, who is ready for deeper investment, or how the network is structured.
+
+When not to use:
+- You already know the one exact item you need to inspect in depth.
+- You are mutating state and only need confirmation of a single write result.
+
+Step-by-step sequence:
+1. Start with `review_affinity` on the highest-level view that matches the question: radar, owner links, progression readiness, graph, moments, or a timeline view.
+2. Use radar when the question is who needs attention now.
+3. Use progression readiness when the question is where additional positive investment is most likely to deepen a relationship.
+4. Use graph review when the question is network shape, bridges, clusters, or hidden centrality.
+5. Use journal or timeline views when a score needs narrative context before action.
+6. Escalate to `inspect_affinity_item` only after the review surface identifies the exact target worth opening deeply.
+
+Validation checks:
+- The chosen review surface actually matches the decision you are trying to make.
+- You inspected context before acting on a surprising score.
+- Follow-up work targets the right contact or link rather than the loudest metric.
+
+Pitfalls:
+- Do not treat radar as a command to act blindly without context.
+- Do not confuse progression readiness with relationship importance; they answer different questions.
+- Do not rely on one score when a timeline or graph view would explain the situation better.
+
+Tips and tricks:
+- Review flows are strongest when used rhythmically rather than sporadically.
+- Use graph review to understand bridges and clusters, then use timeline or profile inspection for the exact story behind them.
+- Empty results can still be informative: they may confirm that maintenance debt is currently low.
+
+Tool calls to prefer:
+- `review_affinity` for all dashboard-style surfaces
+- `inspect_affinity_item` for exact deep follow-up
+
+Related skills:
+- `record-direct-evidence-well`
+- `manage-recurring-dates-and-reminders`
+- `reconcile-duplicates-and-merge-safely`