knowledge-extract

name	knowledge-extract
description	Takes one input (meeting, article, memo) and extracts it in parallel into three entities — person, entity, theme. Use this as the entry point for accumulating raw observation logs into a Markdown + Git LLM Wiki (Axis A immediate task 1). Writes to the wiki via Immediate Fold (append to existing page) by default; when a new page must be created or a duplicate-match decision is required, fires a Review Fold (fold-request event) instead.
license	MIT

knowledge-extract — Parallel extraction from one input into multiple entities

Position of this skill The immediate task 1 of Axis A (how to accumulate knowledge). Converts meetings, articles, and memos into a structured set of wiki pages. Related: docs/A-accumulation/03-multi-perspective.md, docs/A-accumulation/04-signal-scoring.md (immediate task 2 = meeting-signal-assess runs in parallel with this skill only for meeting inputs; it is a separate task).

---

1. What this skill solves

Take a single input (a meeting, an article, a memo) and decompose it in parallel from multiple perspectives into a form the wiki can reuse.

Perspective	Wiki output target	Examples
Person	people/{slug}.md	The meeting counterpart, the article's author, a person mentioned in a memo
Entity (company / project)	entities/{slug}.md (only when applicable)	The counterpart's company, a company mentioned in an article
Theme	themes/{slug}.md (append to observation log of an existing theme)	A theme raised in the meeting, the main topic of the article

So that all three perspectives can be extracted in one prompt, this skill is designed to finish in a single LLM call. Splitting the call into three perspective-wise calls gives the same result and is fine if preferred.

---

2. Design principles

• One input → multiple parallel outputs: people / entities / themes are emitted in parallel within one task
• Bias toward keeping candidates: do not drop candidates for being duplicates or low-resolution. Only drop a candidate when the edit would erase existing information, when there is a clear contradiction, when external input leaks in, or when the assertion has no backing
• No overwrite — append only: all writes to existing pages are time-ordered appends (- YYYY-MM-DD: content). Past entries are never removed
• Separation of raw / verified: every output from this skill is a raw observation log. Verified facts that have passed fact-checking are the responsibility of Axis B (long-form-analysis) (see docs/00-philosophy.md §4)
• Immediate Fold first: appends to an existing page run immediately; new-page creation, duplicate-match decisions, and "the target section does not exist" cases are routed to Review Fold
• Do not apply writing-humanizer-ja: the output of this skill is structured data. Naturalizing the prose is unnecessary — in fact, the mechanical format of the one-line summaries makes downstream aggregation easier

---

3. Execution flow

Input (inbox/<file>.md, or one file specified by an event payload)
   │
   ▼
Stage 0: Preparation (scan themes/_index.md and people/_index.md)
   │
   ▼
Step 1: Read the source, decide source_type / context
   │
   ▼ (parallelizable)
   ├──────────┬──────────┐
   ▼          ▼          ▼
Step 2:    Step 3:    Step 4:
Person     Entity /   Theme match +
extraction  project    append to
(people)   extraction  observation log
           (entities,    (themes)
           when applicable)
   │          │          │
   └────┬─────┴──────────┘
        │
        ▼
Step 5: Append to log.md (a list of pages updated this run)
   │
   ▼
Step 6: Flip the input file's status from pending to processed
   │
   ▼
Done (Immediate Fold appended to 1-3 pages; any Review Fold candidates have been fired into events/queue/)

---

4. Prerequisite: minimum wiki layout

This skill assumes the following minimum wiki layout already exists. If a fresh clone does not have it, bootstrap it by copying these files from this repository's templates/ directory:

Copy from	Copy to	Purpose
templates/_inbox.md	inbox/<YYYY-MM-DD>-<slug>.md	Template for one input
templates/_theme-index.md	themes/_index.md	Active theme catalog (required)
templates/_theme.md	themes/<slug>.md	Per-theme page (add as needed)
templates/_person.md	people/<slug>.md	Person page (created after Review Fold approval)
templates/_entity.md	entities/<slug>.md	Entity page (created after Review Fold approval)
templates/_log.md	log.md	Append-only activity log (required)

Minimum-wiki bootstrap steps:

# Pick a wiki root and cd into it
mkdir -p <wiki>
cd <wiki>

# Create the required directories + files
mkdir -p inbox people entities themes events/queue events/processed
cp <repo>/templates/_theme-index.md themes/_index.md
cp <repo>/templates/_log.md log.md

# Optionally prepare one initial theme
cp <repo>/templates/_theme.md themes/<first-theme>.md

That gives you themes/_index.md (required) + log.md (required) + one theme file + empty inbox / people / entities / events directories.

Do not copy the remaining three templates (_inbox.md / _person.md / _entity.md) at bootstrap time. Use them at the following moments:

Template	When to use	Copy to
templates/_inbox.md	Every time a new input is ingested	inbox/<YYYY-MM-DD>-<slug>.md
templates/_person.md	After a Review Fold approves a new person page (human judgment)	people/<slug>.md
templates/_entity.md	After a Review Fold approves a new entity page (human judgment)	entities/<slug>.md

Bootstrap only needs the minimal runtime. New inbox / person / entity files get added as they show up.

The minimum wiki layout is defined as:

<wiki>/
├── inbox/                       # Input staging
│   └── <YYYY-MM-DD-slug>.md     # 1 file = 1 input
├── people/                      # Person pages
│   └── _index.md                # (optional) person catalog
├── entities/                    # Entity / project pages
│   └── _index.md                # (optional) entity catalog
├── themes/                      # Theme pages
│   ├── _index.md                # Catalog of active themes (required)
│   └── <slug>.md                # Per-theme file (has an "Observation log" section)
├── log.md                       # Append-only activity log (required)
└── events/
    ├── queue/                   # Unprocessed events
    └── processed/               # Processed events

4.1 Minimum skeletons of each file

themes/_index.md (catalog of active themes):

# Themes Index

| Slug | Title | Status |
|---|---|---|
| agent-governance | AI agent operational governance / misbehavior monitoring | active |
| <other-theme> | <Title> | active |

themes/<slug>.md (per-theme file, minimal):

---
name: <Slug>
status: active
---

# Overview
<1-3 lines describing this theme>

# Verified facts (verified)
<Folded in by Axis B's long-form-analysis. This skill does not touch this section>

# Observation log (raw)
<Time-ordered observation log this skill appends to>

log.md (minimum skeleton of the append-only activity log):

# Activity Log

<!-- knowledge-extract / knowledge-consolidation / long-form-analysis etc. append here, append-only -->

templates/_inbox.md (template for a new inbox file):

---
source_type:           # meeting_note | article | manual_memo | external_web
date: YYYY-MM-DD
title:
status: pending
participants:          # only when source_type=meeting_note
  -
url:                   # only when source_type=article or external_web
context:               # discovery | tracking | stakeholder | research | personal | other
---

<body>

4.2 When the layout is incomplete

• themes/_index.md missing → halt (Step 4's theme matching has no base to read)
• log.md missing → auto-create as empty file and continue
• events/queue/ missing → auto-create and continue
• <wiki>/people/ or <wiki>/entities/ missing → auto-create and continue (person / entity extraction still runs; every new candidate goes to Review Fold)

---

5. Stage 0: preparation

Before execution, confirm the following three points.

5.1 Read the existing wiki index

ls <wiki>/people/         # existing people list
ls <wiki>/entities/       # existing entity (company / project) list
cat <wiki>/themes/_index.md   # existing theme list (YAML or Markdown)

This gives the analyst the material to decide "new page vs append to existing". Generate slug candidates in kebab-case English or romaji.

5.2 Confirm the input file's frontmatter

The input is <wiki>/inbox/<file>.md (or the .md file pointed to by an event payload's payload_ref). It should have these fields:

---
source_type: meeting_note | article | manual_memo | external_web
date: YYYY-MM-DD
title: <source title>
status: pending
participants:               # only when source_type=meeting_note
  - <name> (<affiliation>)
url:                        # only when source_type=article or external_web
---

If source_type is unset, halt the run and either ask a human to label it, or infer it from the body (when inferred, add source_type_inferred: true to the frontmatter).

5.3 Check the confidential area

When the input contains any of the following, exclude them from what gets written to the wiki side (people / entities / themes). Safer to not write them into the analysis artifact either:

• Specific monetary figures / valuations / ratio numbers
• External-stakeholder names / candidate-identifying information
• Details of important decisions / decision processes
• Specific compensation / individual HR-evaluation numbers
• Email addresses / phone numbers / personal IDs / full raw transcripts
• Specific undisclosed-strategy timelines

When in doubt, do not write to the wiki. Err on the safe side.

---

6. Step 1: read the source + decide context

Read the input body and decide the following.

Decision	Value	Effect
source_type	meeting_note / article / manual_memo / external_web	Extraction policy for Steps 2-4
context	discovery / tracking / stakeholder / research / personal / other	Whether Step 3 (entity extraction) needs to cross-check against an external entity index
participants count	0 / 1+	Number of targets in Step 2 (person extraction)
external_input	true / false	When external, treat as untrusted (apply §5.3 confidential check more strictly)

Keep the decisions as an internal memo and use them while running Steps 2-4.

---

7. Step 2: person extraction (people/)

7.1 Extraction targets

source_type	Persons to extract
meeting_note	All participants (excluding self)
article	The author + people mentioned by name in the article (about 1-3 people)
manual_memo	People mentioned by name in the memo (about 0-3 people)
external_web	The main people mentioned by name in the article

Exclude peripheral people whose name merely appears. Extract only the people central to the content.

7.2 Processing

For each person:

1. Generate a slug (kebab-case English, or romanized surname-given name)
   • Example: Jane Doe → jane-doe; 山田太郎 → yamada-taro
2. Check whether <wiki>/people/{slug}.md exists
3. If the page exists (Immediate Fold):
   • Append one line to the "Interactions" section:
     • - YYYY-MM-DD: [<input title>] <one-sentence summary> (source: inbox/<source_file>)
4. If a new page is needed (Review Fold):
   • Fire a knowledge-fold-request event into events/queue/ (details in §12)
   • Do not create the new page via Immediate Fold

7.3 Granularity of the "Interactions" section

One interaction line is fact-based, no speculation. When speculation is included, mark it (speculation) explicitly.

Good example:

- 2026-04-20: [Acme AI Inc discovery meeting] Preparing a B2B SaaS in the AI agent governance space. Stated 4x growth in agent count over the last 6 months (source: inbox/2026-04-20-acme-ai-meeting.md)

Bad example (speculation leaks in):

- 2026-04-20: Growing fast and looks promising ← speculation, not fact-based

---

8. Step 3: entity / project extraction (entities/, when applicable)

8.1 Extraction condition

Run only when source_type is meeting_note, context is one of discovery / tracking / stakeholder, and a company name is identifiable.

For article or manual_memo, extract if a company is clearly the subject. If the call is uncertain, route to Review Fold.

8.2 Processing

1. Search <wiki>/entities/ by the company-name slug
2. If entities/{slug}.md exists (Immediate Fold):
   • Append one line to the trailing "Observation log" section
3. Search any existing external entity index (if you keep one):
   • If your organization keeps an external tracking catalog at <wiki>/external-entity-index/ or similar, check whether an entry already exists there
   • On a hit, append to its "Observation log" trailing section
4. No hit + the context is important entity-tracking:
   • Route to Review Fold (new-page creation requires human review)
5. Not a tracking context (personal memo / small talk): skip

8.3 Granularity of the "Observation log" section

Entity observation logs are fact-based. State phase changes (e.g. status: candidate → exploring) explicitly.

- 2026-04-20: [<input title>] 4x growth in agent count over the last 6 months; unmet pain in misbehavior monitoring. status: exploring (source: inbox/<source_file>)

---

9. Step 4: theme match + append to observation log (themes/)

9.1 Theme matching

1. Extract keywords from the input body (the LLM reads it and proposes theme candidates)
2. Match against existing themes in <wiki>/themes/_index.md
3. For each matched existing theme, append one line to the observation log (Immediate Fold)
4. For new theme candidates, route to Review Fold (adding a new theme is a human decision)

9.2 Granularity of the observation-log append

Append one line to the "Observation log" section of themes/{slug}.md. Do not write to the "Verified facts" section (this skill produces raw observations; verified facts are Axis B's responsibility).

# Observation log (raw)

- 2026-04-20: [Acme AI Inc discovery meeting] In the AI agent governance space, misbehavior-monitoring pain has surfaced; observed in a customer in the agent-count-spike phase (source: inbox/2026-04-20-acme-ai-meeting.md)

When multiple themes match, append one line to each theme file.

9.3 When the section does not exist

If themes/{slug}.md lacks an "Observation log" section, do not Immediate Fold; route to Review Fold (a human decides the section design).

---

10. Step 5: append to log.md

Append one block to the tail of <wiki>/log.md summarizing this run.

## [2026-04-20] ingest | Acme AI Inc discovery meeting

- source: inbox/2026-04-20-acme-ai-meeting.md
- New candidates (consolidated into Review Fold): people/jane-doe.md, people/john-smith.md, entities/acme-ai-inc.md
- Appended (Immediate Fold): themes/agent-governance.md (1 observation-log line)
- Review Fold fired: **1 event (a single fold-request bundling all 3 candidates)**: events/queue/<event-id>.md
- Immediate Fold applied: 1
- Gist: B2B SaaS in AI agent governance; misbehavior-monitoring pain surfacing in customers in the agent-count-spike phase

The log is append-only. Existing entries are not touched.

---

11. Step 6: update input file / event status

Branch based on the trigger (direct inbox vs event).

11.1 Direct inbox trigger (the file was processed directly while status: pending)

Flip the input file's (inbox/<file>.md) status from pending to processed.

---
source_type: meeting_note
date: 2026-04-20
title: Acme AI Inc discovery meeting
status: processed     # ← updated from pending
processed_at: 2026-04-20T16:00:00+09:00
processed_by: knowledge-extract
---

11.2 Event-triggered (started from a knowledge-extract event in events/queue/)

Update both:

1. Update the input file's status (same procedure as §11.1, on the file pointed to by payload_ref)
2. Move the event file: mv events/queue/<event-id>.md events/processed/<event-id>.md (leaving it in queue/ causes reprocessing)

mv events/queue/<event-id>.md events/processed/<event-id>.md

Alternatively, in implementations that do not use events/processed/, add event_status: processed and processed_at: <ISO 8601> to the event-file frontmatter to mark completion in-queue.

11.3 In either path

This prevents duplicate processing the next time knowledge-extract runs.

---

12. Review Fold event fire format

When Review Fold is required for any of new-page creation / duplicate-match decision / missing section / confidential-area judgment, create the following event file in events/queue/.

---
id: evt-<UUID or timestamp>
scope: <wiki scope, e.g. personal / team / org>
source: knowledge-extract
target: <reviewing role, e.g. research / knowledge-owner>
type: knowledge-fold-request
priority: normal     # low / normal / high (use high when a confidentiality decision is pending)
created: 2026-04-20T16:00:00+09:00
payload_ref: inbox/<source_file>
chain_depth: 0
---

# Knowledge Fold Request: <input title>

## Fold candidates

### New-page candidates

- people/jane-doe.md - Acme AI Inc CEO, appeared as meeting counterpart
- people/john-smith.md - Acme AI Inc CTO, appeared as meeting counterpart
- entities/acme-ai-inc.md - B2B SaaS in agent governance space, status: candidate

### Existing-page append candidates (where Immediate Fold was uncertain: 3+ files / missing section / pending confidentiality decision, etc.)

- themes/<candidate-theme>.md - target section missing; a human must decide section design

## Inferred category

people / entities / themes / decisions / ideas (which one, with reasoning)

## Gist

Summary in 5 lines or fewer

The receiving side (a human, or the weekly aggregation task) reviews and folds into the wiki.

---

13. Quality gate (pre-completion checks, mechanically verifiable)

Treat completion as conditional on all of the following.

• Input frontmatter completeness: source_type, date, title, status are present (Stage 0)
• Coverage of the 3 perspectives: people / entities (when applicable) / themes have either been extracted, or "not applicable" is stated explicitly (Steps 2-4)
• Immediate Fold rule compliance: every page Immediate-Fold-appended is an existing page, and the target section is one of "Interactions" (people) / "Observation log" (entities, themes). New-page creation and writes to the "Verified facts" section go only via Review Fold
• Review Fold event completeness: every fired fold-request event has the 9 fields id, scope, source, target, type, priority, created, payload_ref, chain_depth plus the body (fold candidates / inferred category / gist)
• Appended lines are fact-based: every appended line follows the format YYYY-MM-DD: [input title] <one fact-based sentence> (source: <source_file>). Any speculation is explicitly marked (speculation)
• Confidential area excluded: the checklist in §5.3 has not leaked into the wiki side
• log.md appended: the corresponding ingest entry has been added as one block to <wiki>/log.md
• Input file status updated: the input file's status has been flipped from pending to processed
• Event trigger marked processed (only for event-triggered runs): events/queue/<event-id>.md has been moved to events/processed/<event-id>.md, or the event-file frontmatter has been given event_status: processed and processed_at (see §11.2; an event left in queue/ causes duplicate execution)

---

14. Synthetic example — processing an Acme AI Inc discovery meeting

14.1 Input (inbox/2026-04-20-acme-ai-meeting.md)

---
source_type: meeting_note
date: 2026-04-20
title: Acme AI Inc discovery meeting
status: pending
participants:
  - Jane Doe (Acme AI Inc CEO)
  - John Smith (Acme AI Inc CTO)
context: discovery
---

# Acme AI Inc discovery meeting

Participants: Acme AI's Jane Doe (CEO) and John Smith (CTO).
Topic: Acme AI is preparing a B2B SaaS in the agent governance space.
Agent count grew from 300 to 1,200 over the last 6 months, but misbehavior monitoring is thin.
The note-taker stated, "agent governance is on our theme-tracking list."

14.2 Stage 0 confirmation (pre-state)

• people/jane-doe.md / people/john-smith.md do not exist → new candidates
• entities/acme-ai-inc.md does not exist → new candidate
• agent-governance exists in themes/_index.md → existing theme
• themes/agent-governance.md pre-state (relevant sections):

---
name: agent-governance
status: active
---

# Overview
A theme covering operational governance / misbehavior monitoring / behavioral constraints of AI agents.

# Observation log (raw)
- 2026-03-15: [<another meeting>] Monitoring needs at the 100+ agent scale surfaced (source: inbox/2026-03-15-...)
- 2026-04-05: [<another article>] An OSS agent-orchestrator announced a new feature (source: inbox/2026-04-05-...)

→ The "Observation log" section exists on the existing page (no new-section creation needed; eligible for Immediate Fold)

• context: discovery → Step 3 (entity extraction) is in scope
• No §5.3 confidential-area hits

14.3 Step 1 decisions

source_type: meeting_note
context: discovery
participants: 2
external_input: false

14.4 Step 2 output (person extraction)

• people/jane-doe.md — new candidate → Review Fold
• people/john-smith.md — new candidate → Review Fold

No Immediate Folds (the existing pages do not exist).

14.5 Step 3 output (entity / project)

• entities/acme-ai-inc.md — new candidate → Review Fold

14.6 Step 4 output (theme match, applied via Immediate Fold)

Append one line to the "Observation log" section of themes/agent-governance.md.

Before (pre-state, as confirmed in §14.2):

# Observation log (raw)
- 2026-03-15: [<another meeting>] Monitoring needs at the 100+ agent scale surfaced (source: inbox/2026-03-15-...)
- 2026-04-05: [<another article>] An OSS agent-orchestrator announced a new feature (source: inbox/2026-04-05-...)

After (post-state, after applying Immediate Fold):

# Observation log (raw)
- 2026-03-15: [<another meeting>] Monitoring needs at the 100+ agent scale surfaced (source: inbox/2026-03-15-...)
- 2026-04-05: [<another article>] An OSS agent-orchestrator announced a new feature (source: inbox/2026-04-05-...)
- 2026-04-20: [Acme AI Inc discovery meeting] Misbehavior-monitoring pain surfacing in the AI agent governance space; observed in a customer in the 4x-agent-growth-in-6-months spike phase (source: inbox/2026-04-20-acme-ai-meeting.md)

No overwrite — one line appended in time order at the tail.

14.7 Step 5 log.md append

## [2026-04-20] ingest | Acme AI Inc discovery meeting

- source: inbox/2026-04-20-acme-ai-meeting.md
- New candidates (consolidated into Review Fold): people/jane-doe.md, people/john-smith.md, entities/acme-ai-inc.md
- Appended (Immediate Fold): themes/agent-governance.md (1 observation-log line)
- Review Fold fired: **1 event (a single fold-request bundling all 3 candidates)**: events/queue/evt-20260420-knowledge-fold.md
- Immediate Fold applied: 1
- Gist: B2B SaaS in AI agent governance; misbehavior-monitoring pain in agent-count-spike customer

14.8 Step 6 input file status update

---
source_type: meeting_note
date: 2026-04-20
title: Acme AI Inc discovery meeting
status: processed
processed_at: 2026-04-20T16:00:00+09:00
processed_by: knowledge-extract
participants:
  - Jane Doe (Acme AI Inc CEO)
  - John Smith (Acme AI Inc CTO)
context: discovery
---

14.9 Review Fold event (events/queue/evt-20260420-knowledge-fold.md, 1 event bundling 3 candidates)

---
id: evt-20260420-knowledge-fold
scope: personal
source: knowledge-extract
target: research
type: knowledge-fold-request
priority: normal
created: 2026-04-20T16:00:00+09:00
payload_ref: inbox/2026-04-20-acme-ai-meeting.md
chain_depth: 0
---

# Knowledge Fold Request: Acme AI Inc discovery meeting

## Fold candidates

### New-page candidates

- people/jane-doe.md - Acme AI Inc CEO, first interaction via the Acme AI Inc discovery meeting
- people/john-smith.md - Acme AI Inc CTO, first interaction via the Acme AI Inc discovery meeting
- entities/acme-ai-inc.md - B2B SaaS in the agent governance space, status: candidate, context: discovery

### Existing-page append candidates (where Immediate Fold was uncertain: 3+ files / missing section / pending confidentiality decision, etc.)

None (all Immediate Fold candidates have been applied)

## Inferred category

- people: 2 new
- entities: 1 new

## Gist

First meeting with Jane Doe (CEO) and John Smith (CTO) of Acme AI Inc. B2B SaaS in the AI agent governance space; 4x agent-count growth over the last 6 months; misbehavior-monitoring pain has surfaced.

14.10 Relationship to immediate task 2 (meeting-signal-assess)

This skill is immediate task 1. For meeting-style inputs, after this skill completes, immediate task 2 (meeting-signal-assess, see docs/A-accumulation/04-signal-scoring.md) runs in parallel. The two tasks do not depend on each other's outputs and may execute in parallel. For article / memo inputs, only this skill runs (see docs/A-accumulation/03-multi-perspective.md §1).

---

15. Common misunderstandings

Q1. "Even if the person is new, can't Immediate Fold create the page?"

No. New-page creation always routes to Review Fold. Two reasons:

• Slug-collision judgment is hard without a human in the loop (same name, transliteration drift)
• For a new person, there is usually not enough information yet (better to accumulate a few interactions via Review Fold first)

Q2. "Same for a new theme — Review Fold?"

Yes. Adding a new theme is a structural change to the wiki, so do not run it immediately. Route to Review Fold and let a human decide whether this is a new theme or an observation-log append on an existing theme.

Q3. "When confidential information is mixed in, is it OK to leave the input as-is in inbox?"

inbox is a staging area. It is acceptable to leave confidential content there (the canonical wiki side is what does not get written). However, when long-term retention is needed for confidential content, moving it to dedicated storage is recommended.

Q4. "Should I apply writing-humanizer-ja?"

No. The output of this skill is structured data and needs no natural-prose style. Keeping the mechanical format (- YYYY-MM-DD: [title] <summary> (source: ...)) makes downstream knowledge-consolidation (weekly aggregation) and query-fold-batch easier to parse.

---

16. Related skills / docs

• docs/00-philosophy.md — Overall philosophy (the two axes / raw/verified separation)
• docs/A-accumulation/03-multi-perspective.md — The full picture of the two immediate parallel tasks
• docs/A-accumulation/04-signal-scoring.md — The internals of immediate task 2 (meeting-signal-assess)
• docs/A-accumulation/06-protected-write-guard.md — Reasoning behind Immediate Fold / Review Fold (Week 2)
• skills/long-form-analysis/SKILL.md — Axis B core (promoting claims to "verified facts" lives there)

---

License

MIT (this skill). See LICENSE at the repo root for details.