@jayjiang/byoao 1.1.2 → 2.0.0

package/dist/assets/skills/challenge.md

@@ -1,11 +1,14 @@
 ---
 name: challenge
-description: Pressure-test a belief, assumption, or decision using the vault's own history. Finds counter-evidence, contradictions, and blind spots. Use when the user says "challenge this", "am I wrong about", "test this assumption", "play devil's advocate", or wants to validate a decision against their own notes.
+description: >
+  Pressure-tests beliefs against vault evidence. Finds contradictions, position changes,
+  unstated assumptions, and weak points in arguments. Use when the user wants to question
+  a decision, test a hypothesis, or find flaws in their reasoning.
 ---
 
-# /challenge — Pressure-Test Your Thinking
+# /challenge — Pressure Test
 
-You are a constructive critic. Your job is to take a belief, assumption, or decision the user holds and rigorously test it against their own vault — finding counter-evidence, contradictions, unstated assumptions, and blind spots. You are not adversarial; you are helping the user think more clearly.
+You are a respectful adversary. Your job is to find the weak points in a belief, decision, or argument — not to be destructive, but to strengthen the user's thinking by exposing vulnerabilities they may have missed.
 
 ## Prerequisites Check
 
@@ -13,162 +16,117 @@ You are a constructive critic. Your job is to take a belief, assumption, or deci
 obsidian --version
 ```
 
-If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
-
-## Tool Selection
-
-Use `obsidian` CLI for content operations (read, search, backlinks, properties, tags). Use BYOAO tools (`byoao_search_vault`, `byoao_graph_health`) when Obsidian CLI is unavailable or for graph-level structural queries.
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
 
 ## Parameters
 
-- **belief** (required): The belief, assumption, or decision to challenge. Can be a direct statement or a reference to a note.
-- **strength** (optional): "gentle" (look for nuances), "rigorous" (find every counter-argument). Default: "rigorous".
-- **output** (optional): Save the challenge analysis as a note.
+- **claim** (required): The belief, decision, or argument to challenge.
+- **scope** (optional): `all` (full vault) or a specific directory/page. Default: `all`.
 
 ## Process
 
-### Step 1: Articulate the Belief
-
-Parse the user's input and restate the belief clearly:
-
-> "The belief being tested: **{clear statement}**"
+### Step 1: Understand the Claim
 
-If the belief references a note, read it and extract the core claim:
+Clarify what exactly is being challenged:
+- What is the core assertion?
+- What assumptions does it rest on?
+- What would falsify it?
 
-```bash
-obsidian read "<note>"
-```
+If the claim is ambiguous, ask the user to clarify before proceeding.
 
 ### Step 2: Find Supporting Evidence
 
-First, be fair — find notes that support the belief:
-
 ```bash
-obsidian search "<key terms from belief>"
+obsidian search "<key terms from claim>"
 ```
 
-Read notes that discuss this topic. Document what supports the belief:
-- Which notes align with it?
-- What evidence was the belief originally based on?
-- How confident does the user seem in their notes?
-
-### Step 3: Find Counter-Evidence
-
-Now actively look for contradictions:
-
-**Direct contradictions** — Notes that explicitly state the opposite.
-
-**Changed positions** — Run a temporal analysis (like /trace):
-- Did the user ever hold a different view?
-- When did it change? What triggered it?
-- Was the change based on new evidence or assumption?
-
-**Unstated assumptions** — What does the belief take for granted?
-- "This assumes that {X} will remain true"
-- "This assumes that {person/team} agrees"
-- "This assumes the current constraints won't change"
-
-**Missing perspectives** — Whose viewpoint is absent?
-- "No notes consider the user/customer perspective"
-- "The cost analysis only covers engineering, not operations"
-
-**Survivorship bias** — Is the vault only tracking successes?
-- "Three similar initiatives are documented, all framed positively. Are there failed attempts that weren't documented?"
-
-### Step 4: Assess Confidence Level
+Read relevant notes and agent pages. Identify:
+- Notes that explicitly support the claim
+- Notes that provide indirect support (data, observations)
+- The strength of each piece of evidence
 
-Based on the evidence gathered, rate the belief:
+### Step 3: Find Contradicting Evidence
 
-| Level | Description |
-|-------|-------------|
-| **Strong** | Consistent support across notes, no meaningful counter-evidence, assumptions are reasonable |
-| **Moderate** | Good support but some counter-evidence exists, or key assumptions are untested |
-| **Weak** | Significant counter-evidence, contradictions over time, or critical unstated assumptions |
-| **Contradicted** | The vault's own history provides stronger evidence against the belief |
+This is the core of /challenge. Search for:
 
-### Step 5: Present the Challenge
+1. **Direct contradictions** — Notes that explicitly state the opposite
+   ```bash
+   obsidian search "not <term>" OR "instead of <term>" OR "changed from <term>"
+   ```
 
-```markdown
-# Challenge: {Belief Statement}
-
-**Confidence level**: {Strong / Moderate / Weak / Contradicted}
-
----
-
-## The Belief
-
-{Restated belief in the user's own words, citing the source note if applicable}
-
-## Supporting Evidence ({N} notes)
-
-- **[[Note]]**: "{quote supporting the belief}"
-- **[[Note]]**: "{quote}"
+2. **Implicit contradictions** — Notes that describe a situation incompatible with the claim
+   - Read pages with shared tags but different conclusions
+   - On related `entities/` and `concepts/` pages, check optional `contradictions` frontmatter (v2: YAML list of other agent page names documenting conflicting claims — see `/cook` Contradiction Handling)
 
-## Counter-Evidence ({N} notes)
+3. **Position changes over time** — Notes that show the user changed their mind
+   ```bash
+   obsidian search "actually" OR "turns out" OR "reconsidered" OR "reversed"
+   ```
 
-### Direct Contradictions
+4. **Weasel words** — Notes that express uncertainty about aspects the claim treats as certain
+   - "might", "probably", "not sure", "need to verify"
+   - These indicate the claim is stronger than the evidence supports
 
-- **[[Note]]** ({date}): "{quote that contradicts the belief}"
-  **Why this matters**: {explanation}
+### Step 4: Identify Unstated Assumptions
 
-### Position Changes Over Time
+For the claim to be true, what else must be true?
 
-- {date range}: You held view X (evidence: [[notes]])
-- {date}: Something shifted (trigger: [[note]])
-- {date range}: You now hold view Y
+- Technical assumptions (about systems, tools, constraints)
+- People assumptions (about availability, skills, priorities)
+- Temporal assumptions (about deadlines, sequencing, stability)
+- External assumptions (about market, users, dependencies)
 
-### Unstated Assumptions
+Check if the vault evidence supports each assumption.
 
-1. **{Assumption}**: {Why this might not hold}
-   Evidence: {what the vault says or doesn't say}
+### Step 5: Assess Evidence Strength
 
-2. **{Assumption}**: {Why this might not hold}
+Rate the overall case:
 
-### Missing Perspectives
+| Strength | Meaning |
+|----------|---------|
+| Strong | Multiple independent sources agree, no contradictions |
+| Moderate | Some support, minor gaps or contradictions |
+| Weak | Limited evidence, significant contradictions or gaps |
+| Unknown | Vault doesn't have enough information |
 
-- {Whose view is absent and why it matters}
+### Step 6: Present the Challenge
 
-## Verdict
-
-{2-3 paragraphs — fair assessment of how the belief holds up. Not a yes/no judgment but a nuanced analysis of where it's strong and where it's vulnerable.}
-
-## Questions to Sit With
+```markdown
+# Challenge: "{claim}"
 
-1. {A question the user should consider — not rhetorical, genuinely open}
-2. {Another question}
-3. {Another question}
+## The Claim
+{Restate the claim clearly}
 
-## Suggested Actions
+## What Rests On This
+{What assumptions does the claim depend on?}
+- {Assumption 1} — {supported / unsupported / contradicted}
+- {Assumption 2} — {supported / unsupported / contradicted}
 
-- {Concrete action if the belief needs revision}
-- {Action to gather missing evidence}
-- {Notes to re-read with fresh eyes}
-```
+## Supporting Evidence
+- [[Note A]]: "{quote}"
+- [[Note B]]: "{quote}"
 
-### Step 6: Save (Optional)
+## Challenging Evidence
+- ⚠ [[Note C]]: "{quote that contradicts or weakens the claim}"
+- ⚠ [[Note D]]: "{quote showing uncertainty or alternative view}"
 
-At the end of your challenge, ask:
+## Position Changes Over Time
+- {date}: [[Note E]] said X
+- {date}: [[Note F]] said Y (contradicts X)
 
-> "Would you like me to save this as a note?"
+## Weak Points
+1. **{Weak point}**: {why it's weak, which note shows it}
+2. **{Weak point}**: {why it's weak, which note shows it}
 
-If the user confirms, save with frontmatter:
+## Overall Assessment
+**Evidence strength**: {Strong / Moderate / Weak / Unknown}
 
-```yaml
----
-title: "Challenge: {Belief}"
-note_type: literature
-type: analysis
-date: <today>
-tags: [challenge, critical-thinking]
----
+{2-3 sentence summary: what the vault evidence suggests about this claim, what's uncertain, and what would strengthen or weaken the case further}
 ```
 
-Use `obsidian create` to save. Ask the user where they'd like it saved.
-
 ## Key Principles
 
-- **Fair, not adversarial**: Always present supporting evidence first. The goal is clear thinking, not winning an argument.
-- **Vault evidence only**: Challenge using the user's own notes, not general knowledge. "Research says X" is not valid here — "Your note from March says X" is.
-- **Name assumptions explicitly**: The most valuable output is often the unstated assumptions, not the direct contradictions.
-- **Questions over conclusions**: End with questions, not verdicts. The user decides what to do with the analysis.
-- **Respect the "strong" result**: If a belief holds up well, say so clearly. Not every challenge needs to find problems.
+- **Respectful opposition.** The goal is to strengthen thinking, not to tear it down. Frame challenges as "here's what to consider" not "you're wrong."
+- **Evidence only.** Every challenge must cite specific vault notes. Don't invent external counterarguments.
+- **Surface uncertainty.** If the vault shows doubt or hesitation about aspects the claim treats as certain, highlight this gap.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.

package/dist/assets/skills/connect.md

@@ -1,11 +1,14 @@
 ---
 name: connect
-description: Bridge two seemingly unrelated topics or domains using the vault's link graph. Discovers hidden paths and shared contexts. Use when the user asks "how are X and Y related", "is there a connection between", "bridge these topics", or wants to find overlap between two areas of their knowledge.
+description: >
+  Bridges two topics using the link graph, shared people, tags, domains, and conceptual
+  overlap. Use when the user asks "what's the relationship between X and Y", "connect A to B",
+  or wants to understand how two topics relate.
 ---
 
-# /connect — Bridge Two Domains
+# /connect — Bridge Two Topics
 
-You are a knowledge connector. Your job is to find the hidden relationship between two topics the user thinks are unrelated — using their own vault's link graph, shared references, and overlapping contexts to build a bridge.
+You are a connector. Your job is to find and explain the relationship between two topics using the vault's knowledge graph — shared entities, overlapping concepts, common sources, and structural connections.
 
 ## Prerequisites Check
 
@@ -13,201 +16,110 @@ You are a knowledge connector. Your job is to find the hidden relationship betwe
 obsidian --version
 ```
 
-If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
-
-## Tool Selection
-
-Use `obsidian` CLI for content operations (read, search, backlinks, properties, tags). Use BYOAO tools (`byoao_search_vault`, `byoao_graph_health`) when Obsidian CLI is unavailable or for graph-level structural queries.
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
 
 ## Parameters
 
-- **from** (required): The first topic, concept, domain, or note.
-- **to** (required): The second topic, concept, domain, or note.
-- **output** (optional): If set, save the connection map as a note at this path.
+- **from** (required): First topic or page name.
+- **to** (required): Second topic or page name.
+- **depth** (optional): `direct` (only direct connections) or `expanded` (include indirect paths via intermediate pages). Default: `expanded`.
 
 ## Process
 
-### Step 1: Map Both Endpoints
-
-For each of the two topics (`from` and `to`):
-
-1. **Find the anchor note** — does a vault note exist for this topic?
+### Step 1: Locate Both Topics
 
 ```bash
-obsidian search "<topic>"
+obsidian search "<from>"
+obsidian search "<to>"
 ```
 
-2. **Gather the neighborhood** — all notes that mention or link to this topic:
-
-```bash
-obsidian backlinks "<topic>"
-```
+If `INDEX.base` exists, read it to spot compiled pages for either topic.
 
-3. **Extract properties** — what domains, tags, and references are associated?
+Read any existing agent pages in `entities/`, `concepts/`, `comparisons/`, and `queries/`:
 
 ```bash
-obsidian read "<topic note>"
+obsidian read file="entities/<from>.md"  # if exists
+obsidian read file="concepts/<from>.md"  # if exists
+obsidian read file="comparisons/<from>.md"  # if exists
+obsidian read file="queries/<from>.md"  # if exists
+obsidian read file="entities/<to>.md"    # if exists
+obsidian read file="concepts/<to>.md"    # if exists
+obsidian read file="comparisons/<to>.md"  # if exists
+obsidian read file="queries/<to>.md"    # if exists
 ```
 
-Build a set for each endpoint: `{notes, tags, domains, people, concepts}`.
-
-### Step 2: Find Intersection
-
-Compare the two neighborhoods to find overlap:
-
-**Shared notes**: Notes that mention both topics.
-> "[[Meeting 2026-03-15]] discusses both 'rate limiting' and 'user onboarding'."
-
-**Shared people**: People connected to both topics.
-> "[[Alice]] appears in notes about both domains."
-
-**Shared tags**: Tags that appear in both neighborhoods.
-> "Both clusters use #scalability."
-
-**Shared domains**: Notes from both topics that share a `domain` field value.
-
-**Shared references**: Notes in one neighborhood that reference notes in the other.
-
-### Step 3: Find Graph Paths
-
-If direct overlap is sparse, look for indirect paths:
-
-1. For each note in the `from` neighborhood, check its outgoing links
-2. Do any of those linked notes appear in the `to` neighborhood?
-3. If not, go one hop further — check the links of those linked notes
-
-This finds paths like:
-> `from` → [[Note A]] → [[Note B]] → `to`
-
-Report the shortest path(s) found, up to 3 hops.
-
-### Step 4: Analyze the Bridge
-
-For each connection found (shared note, person, tag, or path):
-
-1. **Read the bridging notes** to understand the context
-2. **Explain why the connection matters** — what does the bridge reveal?
-3. **Assess strength** — is this a strong thematic link or a coincidental mention?
-
-Classify connections:
-- **Strong**: Shared context, both topics discussed substantively in the same note
-- **Moderate**: Shared person/tag, indirect but meaningful relationship
-- **Weak**: Coincidental co-occurrence, shared only through generic tags
-
-### Step 5: Synthesize
-
-Build a narrative that explains how the two topics connect:
+### Step 2: Map Each Topic's Connections
 
-```markdown
-# Connect: {From} ↔ {To}
-
-## The Bridge
-
-{1-2 paragraph narrative explaining the connection in plain language}
-
-## Connection Map
-
-### Direct Links ({N} found)
-
-- **[[Shared Note]]** — {how it connects both topics}
-  > "{quote showing from-topic}" ... "{quote showing to-topic}"
-
-### Through People
+For each topic:
 
-- **[[Person]]** — involved in both {from} and {to}
-  - {from} context: {brief description}
-  - {to} context: {brief description}
-
-### Through Concepts
-
-- **[[Concept]]** — shared foundation
-  - Links to {from} via: [[note1]], [[note2]]
-  - Links to {to} via: [[note3]], [[note4]]
-
-### Graph Path
-
-```
-[[from-note]] → [[intermediate]] → [[to-note]]
+```bash
+obsidian backlinks "<from>"
+obsidian backlinks "<to>"
 ```
 
-{Explain what this path reveals}
+Read the pages that link to each topic. Build a connection map:
+- Direct wikilinks (both topics link to the same page, or the same page links to both)
+- Shared tags (use `SCHEMA.md` for taxonomy context when classifying)
+- Shared domain
+- Shared source notes (both topics were extracted from the same user note)
+- Shared people/entities mentioned in both topics' pages
 
-## Strength Assessment
+### Step 3: Find Direct Connections
 
-- **Overall**: {Strong / Moderate / Weak}
-- **Evidence**: {N} shared notes, {N} shared people, {N} graph paths
-- **Confidence**: {High — solid thematic overlap / Medium — circumstantial / Low — tenuous}
+Check if there's already a direct relationship:
+- Does the `from` page wikilink to `to` (or vice versa)?
+- Is there a `comparisons/` page that covers both?
+- Do they share a `sources` entry in frontmatter?
 
-## Potential Insights
+### Step 4: Find Indirect Paths (Expanded Mode)
 
-1. {What the user might learn from this connection}
-2. {How this could inform decisions in either domain}
-3. {A question this connection raises}
+If no direct connection exists, search for intermediate pages:
 
-## Suggested Actions
+1. Find all pages that link to `from`
+2. For each of those, check if they link to `to`
+3. If yes: `from` → `intermediate` → `to` is a connection path
+4. Report the shortest path(s) and explain the relationship
 
-- Link [[Note A]] to [[Note B]] — they discuss the same problem from different angles
-- Add "{from}" as a reference in [[relevant to-note]]
-- Consider creating a hub note for the bridging concept
-```
-
-### Step 6: Handle No Connection
+Also check:
+- Shared tag clusters (both topics use tags that co-occur frequently)
+- Shared domain context (both are about the same domain but different aspects)
+- Temporal overlap (both topics emerged around the same time)
 
-If no meaningful connection is found after searching:
+### Step 5: Present the Connection
 
 ```markdown
-# Connect: {From} ↔ {To}
-
-No meaningful connection found in this vault.
-
-## What I Checked
-
-- Searched {N} notes in the {from} neighborhood
-- Searched {N} notes in the {to} neighborhood
-- Checked up to 3-hop graph paths
-- Compared tags, domains, people, and references
-
-## Possible Reasons
+# Connection: [[{from}]] ↔ [[{to}]]
 
-- These topics genuinely haven't intersected in your notes yet
-- The connection might exist in knowledge you haven't written down
-- Try narrowing the topics or running /emerge to find broader patterns
+## Direct Relationship
+{Yes/No} — {explain the direct connection if it exists}
 
-## Want to Create a Connection?
+## Connection Paths
+{If indirect paths exist, show them:}
 
-If you believe these topics are related, consider:
-1. Writing a note that explicitly bridges them
-2. Adding shared tags or domain fields
-3. Running /weave after writing the bridge note
-```
-
-### Step 7: Save (Optional)
-
-At the end of your analysis, ask:
+1. [[{from}]] → [[{intermediate}]] → [[{to}]]
+   - Path explanation: {how they connect through this intermediate}
 
-> "Would you like me to save this as a note?"
+## Shared Context
+- **Shared tags**: {tag1}, {tag2}
+- **Shared domain**: {domain}
+- **Shared sources**: [[source-note-1]], [[source-note-2]]
+- **Shared entities**: [[entity-1]], [[entity-2]]
 
-If the user confirms, save with frontmatter:
+## Relationship Type
+{Classify the relationship:}
+- **Dependency**: {from} depends on {to} (or vice versa)
+- **Sibling**: Both are aspects of a larger concept
+- **Contrast**: They represent opposing approaches
+- **Evolution**: {to} evolved from {from} over time
+- **Parallel**: Independent topics that happen to share context
 
-```yaml
----
-title: "Connect: {From} ↔ {To}"
-note_type: literature
-type: analysis
-date: <today>
-references:
-  - "[[from-anchor]]"
-  - "[[to-anchor]]"
-tags: [connect, bridge]
----
+## Why This Connection Matters
+{2-3 sentences on what this relationship reveals and why it's worth knowing}
 ```
 
-Use `obsidian create` to save. Ask the user where they'd like it saved.
-
 ## Key Principles
 
-- **Evidence-based**: Every claimed connection must cite specific notes and quotes.
-- **Honest about weakness**: If the connection is tenuous, say so. A weak bridge honestly reported is more valuable than a fabricated strong one.
-- **User's vault only**: Don't bridge topics using your general knowledge. The connection must exist in the vault's own link graph and content.
-- **Actionable**: Always suggest concrete next steps — notes to link, hub notes to create, follow-up traces to run.
-- **Respect the "no connection" result**: Not finding a connection is a valid and useful outcome.
+- **Graph over guesswork.** Base connections on actual wikilinks, shared tags, and shared sources — not inferred relationships.
+- **Multiple paths.** There may be several ways two topics connect — show the most meaningful ones, not just the shortest.
+- **Explain, don't just list.** The value is in the *explanation* of why the connection matters, not just the path itself.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.