# Generate Note From Sources

> Run a repository-scoped, traceable materials-to-note workflow for any user-defined source material. Use when Codex must resolve a subject, entry, admitted sources, output note, subject-local style rules, evidence mappings, non-overwrite controls, run state, resume, or validation while creating a raw note.

- Skill: `jm-frank/generate-note-from-sources` (Agent Skill, multi-file: 30 files)
- Install (CLI): `npx skillmds@latest add jm-frank/generate-note-from-sources`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jm-frank/generate-note-from-sources/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: JM-FRANK (https://skillmd.com/u/jm-frank)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jm-frank/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](references/first-run.md) 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](references/source-views.md), 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](references/persistence-contract.md). 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](references/naming-and-title.md) only when generating, parsing, or validating a name/title.
- Read [Note Style JSON](references/note-style-json.md) only for style validation, extraction, creation, inspection, or migration.
- Read [Evidence Mapping](references/evidence-mapping.md) only when creating or validating mappings and native locators.
- Read [Source Views](references/source-views.md) only when preparing, consuming, diagnosing, or cleaning source readability caches.
- Read [Persistence Contract](references/persistence-contract.md) for run artifacts, preflight, resume, cleanup, retention, or failure preservation.
- Read [Validation Contract](references/validation-contract.md) only when validating, finalizing, or repairing a v3 run.
- Read [TOOLING.md](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.