obsidian-llm-wiki / inspool-wiki-en

# Inspool Wiki Maintenance Rules

This file is the single authoritative rule entry point for the `inspool-wiki-en/` workspace and guides agents that maintain this knowledge base.

## Core Goal

Gradually compile scattered raw material into a structured, cross-referenced, continuously evolving English wiki.

The agent's job is not to improvise one-off answers. The job is to maintain the knowledge structure itself.

## Default Language

- The default language preference for this workspace is English.
- Unless the user explicitly requests another language, agents should write, update, and organize documents in English.
- This applies to page content, documentation, indexes, logs, and command templates.
- Raw source material may remain in its original language and does not need forced translation, but the wiki layer should default to English.

## Three-Layer Structure

### 1. `raw/`

- Stores raw source material such as web clips, articles, book excerpts, meeting notes, PDF transcripts, screenshots, and similar inputs.
- This is the factual source layer.
- The body is read-only by default.
- Only two workflow-level changes are allowed by default: moving file paths and updating a small amount of frontmatter processing metadata.
- Unless the user explicitly asks for it, do not rewrite, trim, or replace the body content under `raw/`.

### 2. `wiki/`

- Stores the structured knowledge pages maintained by the agent.
- Agents may create, update, rename, and cross-link pages here.
- When answering questions, read and synthesize from this layer first.

### 3. `AGENTS.md`

- Defines structural conventions, page rules, workflow steps, and quality standards.
- If practice reveals a better workflow, evolve this file only with user agreement.

## Directory Conventions

### `raw/`

- `raw/unprocessed/`: newly captured material waiting to be handled
- `raw/processed/`: material that completed ingest and approval
- `raw/assets/`: images, attachments, and other static assets saved from source material
- `raw/index.md`: processing-state index

### `wiki/`

- `wiki/sources/`: summary pages for individual sources
- `wiki/entities/`: pages for people, organizations, products, projects, tools, and other entities
- `wiki/concepts/`: pages for concepts, methods, frameworks, and terms
- `wiki/synthesis/`: topical overviews, comparisons, interim conclusions, and written-back Q&A results
- `wiki/meta/`: overview pages, conventions, scope notes, and maintenance metadata
- `wiki/index.md`: content index
- `wiki/log.md`: timeline log

Notes:

- Users may manually create subfolders under `wiki/concepts/`, `wiki/entities/`, and `wiki/synthesis/` for classification.
- Those subfolders are an organizational layer maintained by the user, not immutable semantic truth.
- Agents must remain compatible with arbitrary nesting inside those directories.

## Page Writing Principles

- Write in English by default unless the user explicitly asks for another language.
- Prefer clear headings and short paragraphs.
- Prefer Obsidian-style wiki links such as `[[Some Concept]]`.
- Add source-page references to important facts when possible.
- Separate facts, judgments, and speculation.
- If sources conflict, record the conflict explicitly instead of smoothing it away.

## User-Managed Classification Directories

- Users may create subfolders under `wiki/concepts/`, `wiki/entities/`, and `wiki/synthesis/`, then move pages into them.
- Treat that as normal maintenance behavior, not an error condition.
- Page type is determined by the top-level directory, such as `concepts / entities / synthesis`, not by deeper subfolder names.
- Deeper subfolders are mainly for user organization; do not overfit your reasoning to those paths.
- Unless the user explicitly asks for it, do not reorganize those classification directories on their behalf.
- When reading, updating, or linting pages, scan all subfolders recursively.

## Path Stability Rules

- Do not hard-code full file paths under `wiki/concepts/...`, `wiki/entities/...`, or `wiki/synthesis/...` as if those paths were part of the knowledge semantics.
- Prefer Obsidian wiki links in body text and frontmatter instead of bare path strings.
- If `[[Page Name]]` or another stable wiki link works, do not write a plain-text path instead.
- When a page is moved into a new classification subfolder, treat that as valid and keep operating normally.
- If classification changes leave stale path references behind, fix the references instead of asking the user to revert the structure.
- The move from `raw/unprocessed/` to `raw/processed/` is a workflow transition, not a stable semantic path.
- Therefore, source-page `raw_note` fields, body links to raw material, and any other explicit raw paths must be updated after approval.

## Evidence Nodes and Graph Principles

- Pages under `wiki/sources/` are evidence nodes in the graph.
- Pages under `wiki/entities/`, `wiki/concepts/`, and `wiki/synthesis/` are knowledge nodes.
- For key conclusions on knowledge pages, prefer links to local `sources` pages instead of direct external URLs.
- External URLs should mainly stay in raw-note frontmatter and in the "Source Information" section of source pages, not as primary graph edges.
- If you can locate a specific source-page section, prefer anchored links such as `[[sources/Some Source#Key Points]]`.
- If a conclusion comes from multiple sources, it may attach to multiple evidence nodes.
- If a conclusion has conflicting sources, record that explicitly in `contradicts` and in a body section on disagreement.

## Relationship Field Conventions

To support both Obsidian Graph and Dataview, each page should maintain:

1. explicit wiki links in the body
2. structured relationship fields in frontmatter

Recommended frontmatter fields:

- General fields:
  - `type`
  - `status`
  - `topic`
  - `updated`
- Preferred fields for source pages:
  - `raw_note`
  - `external_url`
  - `related_entities`
  - `related_concepts`
  - `related_sources`
- Preferred fields for entity, concept, and synthesis pages:
  - `supports`
  - `contradicts`
  - `related_entities`
  - `related_concepts`
  - `related_sources`
  - `related_synthesis`

Prefer local wiki links as field values, for example `[[sources/Some Source]]`.

## Citation and Link-Landing Rules

- Key conclusions, concrete facts, numbers, and controversial judgments should carry evidence links whenever possible.
- In body text, prefer evidence links such as `[[sources/...#some-section]]`.
- In frontmatter, `supports` and `contradicts` should at least point to page-level source nodes.
- If the evidence is insufficient, do not force `supports`; mark the point as "to be confirmed".
- Do not dump large numbers of bare external URLs into knowledge pages; convert them into local source-page links when possible.

## Raw Workflow Metadata

Agents may maintain a small set of workflow fields in raw-note frontmatter to reduce context pressure for later ingest runs.

Recommended fields:

- `processing_status`: `unprocessed`, `pending_review`, or `processed`
- `reviewed_at`: date of user approval
- `processed_at`: date processing completed
- `processed_into`: wiki page(s) generated from the source, preferably the source page path
- `ingest_group`: optional field for explicitly grouping related raw notes

Constraints:

- These are workflow metadata fields, not part of the source body.
- Agents may create and update these fields.
- Agents must not use them as an excuse to tamper with the source body.

## Recommended Page Structures

Not every page has to be identical, but prefer the following structures.

### Source Pages `wiki/sources/`

Recommended sections:

- Source Information
- Core Summary
- Key Points
- Evidence Excerpts
- Extractable Entities
- Extractable Concepts
- Connections to the Existing Wiki
- Open Questions
- Related Sources

### Entity Pages `wiki/entities/`

Recommended sections:

- One-Line Definition
- Background
- Key Attributes
- Supporting Evidence
- Conflicts and Disagreements
- Related Events or Views
- Related Concepts
- Related Sources
- Open Questions

### Concept Pages `wiki/concepts/`

Recommended sections:

- Definition
- Core Mechanism
- Difference From Neighboring Concepts
- Supporting Evidence
- Limits or Counterexamples
- Related Entities
- Related Sources

### Synthesis Pages `wiki/synthesis/`

Recommended sections:

- Topic Description
- Summary of Conclusions
- Supporting Evidence
- Conflicts and Disagreements
- Current Judgment
- Open Questions
- Next Suggestions
- Related Sources

## Source Citation Conventions

- Prefer appending source-page links after important conclusions, for example `See [[sources/Some Article]]`.
- If you can land on a specific section, prefer `See [[sources/Some Article#Key Points]]`.
- If a conclusion comes from multiple sources, list multiple related sources.
- If the source cannot currently be confirmed, do not present the statement as settled fact; mark it as "to be confirmed".

## Three Core Operations

### 1. Ingest

When the user asks to process new material:

1. Scan `raw/unprocessed/` first.
2. Select the next ingest unit instead of mechanically choosing a single file.
3. Read `raw/index.md`.
4. Read and extract the core information from the selected source or source batch.
5. Create or update the corresponding source summary page and attach it to the graph as an evidence node.
6. Update related entity, concept, and synthesis pages, and maintain `supports`, `contradicts`, and relevant wiki links.
7. Update `wiki/index.md`.
8. Append to `wiki/log.md`.
9. Update workflow metadata on the raw files in that ingest unit and mark them `pending_review`.
10. Update `raw/index.md`.
11. Tell the user clearly that ingest completed and approval is now required.

A single ingest run should not stop after generating one summary page. Update multiple related pages when needed.

Raw files may be marked `pending_review` only after wiki updates, log updates, and raw-index updates all succeed.

Do not move raw files into `processed/` during ingest. The move from `unprocessed/` to `processed/` must wait for user approval.

### 1b. Approve

When the user explicitly says the ingest result is correct and can be archived:

1. Scan `raw/unprocessed/` for ingest units marked `pending_review`.
2. Select the batch the user just approved; if unspecified, prefer the batch most recently moved into `pending_review`.
3. Verify again that the related wiki pages and `raw/index.md` entries exist.
4. Record the old path, new path, and `processed_into` value for each raw file in the batch.
5. Update `processing_status` to `processed` for each raw file.
6. Write `reviewed_at`.
7. Fill `processed_at` if needed.
8. Move the raw files in that ingest unit into `raw/processed/`.
9. Repair the old raw paths referenced in the wiki, including at least the source-page `raw_note` field and the body link to raw material.
10. Run a localized self-check to confirm that the old `raw/unprocessed/` paths no longer remain in `wiki/`.
11. Update `raw/index.md`.
12. Append an `approve` log entry to `wiki/log.md`.

Approval should not substantially rewrite wiki prose unless the user explicitly requests revisions during approval.

If the localized self-check in step 10 fails, do not treat the approval as complete. Report the stale paths and continue fixing them or stop with an explicit failure state.

### Ingest Unit Selection Rules

By default, the agent processes the "next batch of pending content". Determine the ingest unit with this priority:

1. If there are subfolders under `raw/unprocessed/`, treat files inside the same subfolder as one ingest unit.
2. If multiple raw files share the same `ingest_group`, treat them as one ingest unit.
3. If the user explicitly says several files should be handled together, treat them as one ingest unit.
4. If there is no grouping signal, treat one file as one ingest unit.

### Batch-Ingest Constraints

- Batch ingest is for a clearly related small group of materials.
- Recommended batch size is 2 to 5 files.
- If a batch contains more than 5 files, prefer splitting it into smaller batches to avoid context overload.
- After batch ingest, update workflow metadata for each raw file in the batch.
- When moving into `processed/`, move the full batch together to avoid half-finished states.

### 2. Query

When the user asks a question:

1. Review `wiki/index.md` first.
2. Read the relevant pages.
3. Synthesize an answer from the existing wiki.
4. For important judgments, prefer local source-page citations and anchors where appropriate.
5. If the answer has durable value, write it back into `wiki/synthesis/` when the user agrees or the scenario clearly calls for it.
6. After writing back, update `wiki/index.md` and `wiki/log.md`.

### 3. Lint

Run periodic health checks on the wiki with attention to:

- orphan pages
- strong claims without source support
- outdated conclusions invalidated by newer material but left unchanged
- frequently mentioned concepts or entities that still lack dedicated pages
- pages with clearly insufficient cross-linking
- duplicate pages or inconsistent naming
- knowledge pages that depend directly on external URLs instead of local source pages
- core pages missing relationship fields such as `supports` or `contradicts`
- pages that contain only frontmatter relationships and no explicit wiki links in the body
- stale path strings or broken directory assumptions left behind after user-driven reclassification
- mismatches between `raw/index.md` and the actual contents of `raw/unprocessed/` and `raw/processed/`
- raw notes left in `pending_review` for too long
- related raw notes that should have been processed as a group but were split apart
- ingest groups so large that they introduce too much context noise

After linting, write the result into `wiki/log.md`.

## Index Rules

`wiki/index.md` is a directory view, not a normal content page.

At minimum it should maintain:

- links to each important page
- a one-line description for each page
- optional topic grouping
- optional source counts or last-updated indicators

Before answering questions, locate relevant pages through `wiki/index.md`.

`raw/index.md` is a workflow view for queue and processed-state tracking. Do not pile workflow logs directly into `wiki/index.md`.

## Log Rules

`wiki/log.md` is a timeline, not a discussion page.

Preferred heading format for each entry:

`## [YYYY-MM-DD] action | title`

Suggested actions:

- `init`
- `ingest`
- `approve`
- `query`
- `lint`
- `refactor`

Each log body should briefly record:

- what was processed
- which pages were created or updated
- whether conflicts or follow-up work were found

## Naming Rules

- Prefer concise, stable, reusable file names.
- Do not create multiple near-synonym file names for the same concept.
- For source summary pages, it is acceptable to preserve the source topic in the file name instead of forcing date prefixes.
- If a naming migration is needed, repair links and indexes together.

## Prohibited Actions

- Do not write unverified speculation as fact.
- Do not delete raw material just to "keep things tidy".
- Do not update page bodies without also maintaining `wiki/index.md` and `wiki/log.md`.
- Do not update the wiki without also maintaining `raw/index.md` and raw-file states.
- Do not move `pending_review` raw files into `processed/` without user approval.
- Do not hide conflict information for appearance reasons.
- Do not dump unstructured blocks of chat transcript into `wiki/`.
- Do not treat external URLs as the main edges in the knowledge graph while ignoring local source pages.
- Do not misclassify user-driven subfolder changes as link errors or structural corruption.

## Default Behavior

- By default, process one ingest unit at a time; that unit may be a single file or a small batch.
- Prefer small, reviewable updates by default.
- Use Markdown by default and avoid introducing unnecessary extra systems.
- Prefer Obsidian wiki links by default and do not depend on an external database.