Utility Script Output Formats and Prefixes in Patent Disclosure Skill

Utility scripts in the handsomestWei/patent-disclosure-skill repository emit structured, machine-readable log lines to stdout using format-specific prefixes like DOCX:, MD:, and VECT: to signal success or failure of file generation operations.

All automation tools in this open-source skill follow a strict logging convention that enables reliable parsing by downstream CI/CD pipelines and shell scripts. Each script produces a distinct file type—ranging from Word documents to vector indices—and reports its status using a capitalized prefix that identifies the output artifact category.

Standardized Logging Conventions

Every utility script adheres to a single-line stdout protocol designed for automation. After completing its primary function, the script prints a status line following the pattern:

PREFIX: ok=1 path=<absolute-or-relative-path>

On failure, the format changes to ok=0 and typically includes an error message. The prefix is always an uppercase identifier ending with a colon (e.g., DOCX:, TEXT:) that corresponds to the output format. This design allows orchestration tools to grep for specific prefixes and extract file paths for subsequent processing steps.

Document Generation Formats

Several scripts handle document conversion and creation, outputting either Microsoft Word files or plain text.

Word Documents (DOCX:)

Scripts that generate .docx files use the DOCX: prefix uniformly. The emit_opinion_docx.py utility converts opinion-statement Markdown into a formatted Word document, emitting DOCX: ok=1 path=<docx-path> upon completion. Similarly, md_to_docx.py performs generic Markdown-to-DOCX conversion for broader tooling use, while redact.py processes existing DOCX files to remove confidential sections before writing a new redacted version. All three report status using the DOCX: identifier.

Plain Text Extraction (TEXT:)

The pdf_text.py script extracts textual content from PDF files and writes it to a .txt file. It uses the TEXT: prefix to report extraction results, printing TEXT: ok=1 path=<txt-path> on successful completion or TEXT: ok=0 followed by error details if the PDF processing fails.

Vault and Knowledge Base Outputs

Scripts managing the Obsidian vault and semantic search infrastructure produce Markdown content, vector indices, and directory structures.

Markdown Artifacts (MD:)

Ingestion scripts that create knowledge-base entries generate Markdown files and log with the MD: prefix. Both ingest_case.py and ingest_playbook.py convert input data into structured .md notes, outputting MD: ok=1 path=<output-md>. The case_md.py utility follows the same convention when creating case-specific Markdown files from raw inputs.

Vector Store Indices (VECT:)

The rebuild_vectors.py script regenerates the semantic-search vector index, writing a Pickle or JSON serialized file to the vault directory. Because this produces an embedded data file rather than a user-readable document, it uses the VECT: prefix, reporting VECT: ok=1 path=<index-file> to indicate the index has been successfully persisted.

Vault Regeneration (VAULT:)

When refresh_vault.py rebuilds the entire Obsidian vault layout—generating or updating multiple Markdown notes across the directory tree—it reports completion using the VAULT: prefix. A successful run outputs VAULT: ok=1, signaling that the vault structure is synchronized without necessarily listing every individual file modified.

Directory Layout Management (LAYOUT:)

The vocab_layout.py script (also referenced as the vault layout utility) updates the hierarchical directory structure and associated Markdown templates across the vault. It uses the LAYOUT: prefix, printing LAYOUT: ok=1 upon successfully reorganizing the vault taxonomy.

Workflow and Reporting Scripts

Automation tools generating playbooks, search reports, and metadata databases use distinct prefixes to differentiate their outputs.

Playbook Creation (PLAY:)

The playbook.py script generates structured YAML playbooks for case workflows. It writes a .yaml file and reports status with the PLAY: prefix, emitting PLAY: ok=1 path=<playbook-file> when the playbook is successfully serialized.

Search Results (REPORT:)

When search_cases.py executes semantic queries against the vector store, it compiles results into a Markdown report. This script uses the REPORT: prefix, outputting REPORT: ok=1 path=<report-md> to indicate the search summary file location.

Metadata Storage (STORE:)

The store.py utility manages the vault’s JSON database, persisting metadata about cases and documents. It logs with the STORE: prefix, printing STORE: ok=1 path=<json-file> upon successfully writing the database file.

Content Processing and Redaction

Specialized utilities handle embedding external assets and sanitizing confidential information.

Asset Embedding (EMBED:)

The embed.py script inserts external assets—such as images or tables—into existing DOCX or Markdown files. Because it modifies documents in-place rather than creating new files from scratch, it uses the EMBED: prefix and reports EMBED: ok=1 (without a mandatory path component) upon successful insertion.

Document Redaction

While redact.py performs sensitive content removal, it follows the same output pattern as other document generators. Because it outputs a sanitized Word document, it utilizes the DOCX: prefix rather than a unique identifier, maintaining consistency with the emit_opinion_docx.py and md_to_docx.py tools.

Parsing Utility Output in Automation

Downstream automation can parse these prefixes to build conditional workflows. For example, a shell script processing a patent opinion might capture the generated DOCX path:

OUTPUT=$(python emit_opinion_docx.py --input opinion.md)
if echo "$OUTPUT" | grep -q "DOCX: ok=1"; then
    FILE_PATH=$(echo "$OUTPUT" | grep -oP 'path=\K[^ ]+')
    echo "Successfully generated: $FILE_PATH"
fi

In Python-based orchestration, regex extraction provides similar capabilities:

import subprocess
import re

result = subprocess.run(
    ["python", "ingest_case.py", "--case", "12345"],
    capture_output=True, text=True
)
match = re.search(r'MD: ok=1 path=(\S+)', result.stdout)
if match:
    markdown_path = match.group(1)
    print(f"Case note created at: {markdown_path}")

Summary

• Consistent Prefixing: Every utility in handsomestWei/patent-disclosure-skill uses a unique uppercase prefix (DOCX:, MD:, VECT:, etc.) to identify its output type.
• Structured Status Lines: Scripts emit single-line status messages containing ok=1 for success or ok=0 for failure, optionally including path=<file> for generated artifacts.
• Format Coverage: Output formats include Word documents (.docx), Markdown (.md), plain text (.txt), YAML playbooks (.yaml), JSON databases, and binary vector indices.
• Automation Ready: The predictable PREFIX: ok=N path=... format enables reliable parsing by shell scripts, CI pipelines, and parent Python processes.

Frequently Asked Questions

What prefix does the patent opinion generator use?

The emit_opinion_docx.py script uses the DOCX: prefix. Upon successfully converting opinion Markdown to a Word document, it prints DOCX: ok=1 path=<docx-path> to stdout.

How do I detect if a vault refresh completed successfully?

Check for the VAULT: prefix in the output of refresh_vault.py. A successful execution emits VAULT: ok=1, while failures report VAULT: ok=0 followed by error details.

Which scripts generate Markdown files versus Word documents?

Scripts using the MD: prefix (ingest_case.py, ingest_playbook.py, case_md.py) generate Markdown files. Scripts using the DOCX: prefix (emit_opinion_docx.py, md_to_docx.py, redact.py) generate Word documents. The search_cases.py tool uses REPORT: but also outputs Markdown.

Can I parse utility output programmatically?

Yes. The single-line format PREFIX: ok=1 path=<file> is designed for programmatic parsing. Use regex patterns like r'PREFIX: ok=1 path=(\S+)' in Python or grep with cut in shell scripts to extract file paths and status codes for workflow automation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}