Generate Note From Sources

Generate Note From Sources

Identity And Boundary

Act as a general materials-to-note run controller. Resolve repository, subject, entry, sources, destinations, outputs, state, hashes, evidence, and failure preservation. Do not supply a content type, semantic transformation, importance rule, ordering rule, note structure, or title composition.

Obtain note semantics only from, in order:

1. explicit requirements in the current request;
2. selected rules from subject-local .note-style.json;
3. a template or neighboring note only when the request or selected style rules explicitly authorize it.

If these inputs do not uniquely determine content processing, ask one consolidated clarification before writing the raw note. Do not write temporary request preferences back to the style file.

Support repository-scoped installation only at .agents/skills/generate-note-from-sources/. Require Python 3.9+, a writable local repository, and subject settings inside that repository. Do not use user-level or global configuration.

Resolve Invocation

1. Resolve the repository root and exactly one subject root.
2. Use only <subject>/.source-note-settings.json. Read First Run completely only when initializing or migrating settings/style.
3. Resolve exactly one current entry, admitted source set, source destination set, run ID, candidate note_name, and raw/refined output pair.
4. Honor explicit user targets. Otherwise use validated subject settings and selected style rules.
5. Complete all ambiguity, path-safety, collision, and non-overwrite checks before any write.
6. Make zero writes and request one consolidated clarification when a material value is unresolved.

Treat style, templates, and neighboring notes as control or optional context, never factual evidence unless explicitly admitted as sources.

Run Workflow

1. Resolve repository root, subject root, and canonical settings.
2. Resolve the current entry, admitted sources, and destinations.
3. Resolve .note-style.json.
4. Resolve candidate note_name and outputs.
5. Complete ambiguity and non-overwrite checks.
6. Validate and hash settings, style, and admitted materials.
7. Use run_artifact_tool.py init to create the run directory, in_progress manifest, and planned operation log.
8. Execute confirmed move, copy, or not-required material operations.
9. Use run_artifact_tool.py record-operation to persist each planned material-operation result; keep init's automatic same-path not_required result.
10. Read Source Views, run the direct source_view_tool.py prepare-run entry, and inspect every admitted source through its original or prepared whole-document representation. When any admitted source is DOC/DOCX and command sandboxing is active, request elevation only for the repository-pinned direct entry before its first run; never elevate generic Python or LibreOffice.
11. Use run_artifact_tool.py record-inspection to persist each source inspection result; source-view readiness never decides semantic priority.
12. Use note_style_tool.py list and extract to load only relevant processing rules.
13. Process sources according to the request and selected processing rules.
14. Use note_title_tool.py only when a configured deterministic title rule applies.
15. Validate note_name; derive raw/refined paths deterministically.
16. Use note_style_tool.py list and extract to load only relevant presentation rules.
17. Generate the raw note with top-level frontmatter status: raw.
18. Resolve the mandatory file-level mapping and any enabled block mappings.
19. Use source_view_tool.py clean-run to delete the reproducible source-view cache.
20. Use run_artifact_tool.py build-index to compute note identity and create source-index.json.
21. Apply any other permitted cleanup only inside the run's generated/ directory.
22. Run the schema v3 validator as the final action.
23. Allow the validator to atomically transition in_progress to completed.

Write the manifest and planned operation log before move, copy, extraction, or raw-note writes. Preserve all persistent evidence and failure records outside generated/.

Deterministic Tools

Use deterministic code for JSON parsing, JSON Pointer, style/title validation, title composition and recognition, regex full matching, literal suffix handling, paths, hashes, timestamps, state transitions, native locators, line ranges, frontmatter status, operation logs, non-overwrite preflight, atomic JSON writes, and validation reports.

Treat documented tool interfaces and referenced contracts as the complete operational API. When the tool documentation is sufficient, call the documented interface and do not inspect the implementation.

Run tool calls in parallel only after confirming that every call is necessary and that the calls are independent. Do not parallelize speculative discovery, selection, or reads whose necessity depends on an earlier result.

Treat the operational workflow as highly deterministic. If its documented contracts and tools cannot resolve an operational problem, stop and report the problem instead of inspecting implementations, inventing an undocumented workaround, or guessing. This stop rule does not apply to the semantic judgment explicitly assigned to the model for note-content generation.

Use source_view_tool.py for format-specific readability preparation. It may decide only whether text and visual representations are technically available. It must pass SRT through unchanged, preserve admitted-source order, prepare whole-document views, and never rank sources or run OCR. Delete its reproducible cache before final validation.

Invoke the executable script directly for source-view preparation. Its reusable elevated approval boundary is the absolute script path followed by prepare-run --repo-root <absolute-repo-root>; keep the run path after that fixed prefix. Do not approve python3, libreoffice, or another generic launcher as a substitute.

Use run_artifact_tool.py instead of model-authored run JSON. Supply only the compact request, inspection/operation outcomes, and semantic evidence mapping described in Persistence Contract. Use its fail command immediately when a run becomes failed or abandoned. Do not edit its generated manifest, operation log, or source index by hand.

For a touched subject migration, run migrate_subject_v3.py plan first. Apply only a ready plan with explicit section assignments and apply --confirm; preserve legacy style, notes, sources, and historical runs.

Never directly cat or load the complete style file during note generation. Load style rules phase by phase: at each workflow step, list only the relevant container and extract only the subtrees needed for that phase. list is a selection aid, not a traversal instruction; never extract every listed child merely because it may become relevant later. Split oversized selections by child key. Use root extraction only for explicit style inspection, repair, or migration.

Use the model for request interpretation, selection of relevant style rules, semantic source transformation, prose/Markdown generation, and consolidated clarification. Deterministic tools must not decide semantic importance or organization.

Reference Routing

• Read Naming And Title only when generating, parsing, or validating a name/title.
• Read Note Style JSON only for style validation, extraction, creation, inspection, or migration.
• Read Evidence Mapping only when creating or validating mappings and native locators.
• Read Source Views only when preparing, consuming, diagnosing, or cleaning source readability caches.
• Read Persistence Contract for run artifacts, preflight, resume, cleanup, retention, or failure preservation.
• Read Validation Contract only when validating, finalizing, or repairing a v3 run.
• Read TOOLING.md only when evaluating later material-processing tool candidates.

Completion Gate

Complete only when the v3 validator confirms canonical paths and hashes; legal state and timestamps; immutable settings/style; finished material operations; a valid raw note; exact naming; mandatory file-level evidence; configured block-level behavior; and persistent evidence outside generated/.

On validation failure, repair only safe current-run artifacts. Otherwise mark the run failed, preserve evidence, and report the structured error. Resume only when the validation contract permits it.

Boundaries

• Never overwrite or delete user content.
• Keep settings and style subject-local; do not create registries, global config, counters, schedules, or Git markers.
• Preserve the source object model; do not infer roles, lineage, derivations, ASR, OCR, or media-processing workflows.
• Do not modify historical completed v2 runs. New production runs use schema v3.