Skip to content

fsbtactic-code/marketing-brain-skill / skills/marketing-brain

marketing-brain

Flagged

Create, improve, research, or audit marketing strategy and execution using a bundled marketing library, verified live primary sources for volatile facts, and clearly labeled agent judgment. Use for full marketing systems, audits, landing pages and CRO, competitor intelligence, brand voice, audience and JTBD research, email sequences, SMM and social content systems, paid ads, headlines, copywriting, positioning, offers, launches, GTM, growth, funnels, retention, pricing, SEO, analytics, attribution, experiments, and consumer or buyer psychology. Trigger for English and Russian requests, including requests for ready-to-use assets.

FileKindSize
SKILL.mdskill md10.6 KB
agents/openai.yamlconfig325 B
assets/BUILD-MANIFEST.jsonconfig1.2 KB
assets/cards.jsonlother21.1 KB
assets/edges.jsonlother33.0 KB
assets/knowledge.sqlitebinary136.0 KB
assets/legacy-library.mbpack.parts/manifest.jsonconfig857 B
assets/legacy-library.mbpack.parts/part-0000.binbinary48.0 MB
assets/legacy-library.mbpack.parts/part-0001.binbinary48.0 MB
assets/legacy-library.mbpack.parts/part-0002.binbinary7.7 MB
assets/research-catalog.jsonlother280.4 KB
assets/source-channels.jsonlother52.1 KB
assets/sources.jsonlother10.2 KB
assets/templates/content-calendar.mdmarkdown1.3 KB
assets/templates/evidence-ledger.mdmarkdown1.3 KB
assets/templates/experiment-backlog.mdmarkdown1.2 KB
assets/templates/issue-registry.mdmarkdown1.2 KB
assets/templates/marketing-brief.mdmarkdown1.6 KB
assets/templates/marketing-system-manifest.jsonconfig1.1 KB
assets/wiki/cards/card_ad_effects_heterogeneous_by_firm.mdmarkdown1.3 KB
assets/wiki/cards/card_ad_roi_measurement_noise.mdmarkdown1.4 KB
assets/wiki/cards/card_choice_overload_context_dependent.mdmarkdown1.4 KB
assets/wiki/cards/card_cost_transparency_context.mdmarkdown1.2 KB
assets/wiki/cards/card_ftc_material_connection_disclosure.mdmarkdown1.4 KB
assets/wiki/cards/card_google_ads_experiment_hygiene.mdmarkdown1.3 KB
assets/wiki/cards/card_google_no_word_count_freshness_trick.mdmarkdown1.2 KB
assets/wiki/cards/card_google_people_first.mdmarkdown1.2 KB
assets/wiki/cards/card_google_who_how_why.mdmarkdown1.1 KB
assets/wiki/cards/card_incrementality_control_group.mdmarkdown1.2 KB
assets/wiki/cards/card_incrementality_precision_stratification.mdmarkdown1.3 KB
assets/wiki/cards/card_short_video_ad_spillover.mdmarkdown1.3 KB
assets/wiki/cards/card_telegram_ad_format.mdmarkdown1.0 KB
assets/wiki/cards/card_telegram_destination_quality.mdmarkdown1.1 KB
assets/wiki/cards/card_telegram_no_unsupported_absolutes.mdmarkdown1.0 KB
assets/wiki/cards/card_viral_content_arousal.mdmarkdown1.3 KB
assets/wiki/cards/card_youtube_audience_signals.mdmarkdown1.2 KB
assets/wiki/cards/card_youtube_publish_time.mdmarkdown1.4 KB
assets/wiki/cards/card_youtube_quality_over_frequency.mdmarkdown1.3 KB
assets/wiki/cards/card_youtube_search_ranking.mdmarkdown1.1 KB
assets/wiki/cards/card_youtube_tags_low_priority.mdmarkdown1019 B
assets/wiki/domains/consumer-behavior.mdmarkdown2.2 KB
assets/wiki/domains/content-editorial.mdmarkdown5.1 KB
assets/wiki/domains/creator-community.mdmarkdown1009 B
assets/wiki/domains/cro-funnels.mdmarkdown2.3 KB
assets/wiki/domains/law-policy-ethics.mdmarkdown2.8 KB
assets/wiki/domains/measurement-analytics.mdmarkdown4.5 KB
assets/wiki/domains/offer-messaging-copy.mdmarkdown2.7 KB
assets/wiki/domains/organic-smm.mdmarkdown4.9 KB
assets/wiki/domains/paid-acquisition.mdmarkdown6.2 KB
assets/wiki/domains/pricing-promotions.mdmarkdown850 B
assets/wiki/domains/seo-geo-ai-search.mdmarkdown2.8 KB
assets/wiki/domains/strategy-research.mdmarkdown932 B
assets/wiki/index.mdmarkdown935 B
assets/wiki/open-questions.mdmarkdown159 B
assets/wiki/pages.jsonlother18.3 KB
references/research-catalog-policy.mdmarkdown1.3 KB
references/retrieval-policy.mdmarkdown1.0 KB
references/task-playbooks.mdmarkdown5.1 KB
references/taxonomy.mdmarkdown1005 B
references/third-party-notices.mdmarkdown1.6 KB
references/workflow-audience.mdmarkdown8.4 KB
references/workflow-audit.mdmarkdown7.0 KB
references/workflow-brand-voice.mdmarkdown8.0 KB
references/workflow-competitors.mdmarkdown7.2 KB
references/workflow-email.mdmarkdown8.8 KB
references/workflow-full-system.mdmarkdown9.2 KB
references/workflow-headlines.mdmarkdown8.4 KB
references/workflow-landing-cro.mdmarkdown6.9 KB
references/workflow-paid-ads.mdmarkdown10.1 KB
references/workflow-social.mdmarkdown9.2 KB
scripts/marketing_context_output.pyscript7.3 KB
scripts/marketing_context_query.pyscript8.6 KB
scripts/materialize_legacy_pack.pyscript12.1 KB
scripts/mbpack_codec.pyscript4.1 KB
scripts/mbpack_output.pyscript5.2 KB
scripts/retrieve_marketing_context.pyscript13.1 KB
scripts/search_knowledge.pyscript7.2 KB
scripts/search_legacy_pack.pyscript131 B
scripts/search_private_pack.pyscript11.0 KB
scripts/search_research_catalog.pyscript6.2 KB
scripts/verify_public_install.pyscript7.1 KB

scripts/retrieve_marketing_context.py

View on GitHub
from __future__ import annotations

import argparse
import json
import sqlite3
from pathlib import Path
from typing import Any, Sequence

from marketing_context_output import (
    LEGACY_RISK_GUIDANCE,
    UNKNOWN_RISK_GUIDANCE,
    compact_card,
    compact_lead,
    legacy_usage_guidance,
    render_markdown,
)
from marketing_context_query import (
    card_relevance,
    coverage_rank,
    relevance_terms,
    resolve_domain,
    russian_query_expansion,
    summarize_verified_coverage,
)
from search_knowledge import search_jsonl, search_sqlite
from search_private_pack import (
    configure_utf8_streams,
    connect_readonly,
    read_manifest,
    resolve_pack,
    result_rows,
    retrieve,
)
from search_research_catalog import read_catalog, search_catalog

def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Build a compact evidence bundle for a marketing task.",
    )
    parser.add_argument("--query", required=True)
    parser.add_argument("--domain")
    parser.add_argument("--limit", type=int, default=5)
    parser.add_argument("--max-characters", type=int, default=1200)
    parser.add_argument("--pack", type=Path)
    parser.add_argument("--include-discovery", action="store_true")
    parser.add_argument("--json", action="store_true", dest="as_json")
    arguments = parser.parse_args(argv)
    arguments.limit = max(1, min(arguments.limit, 8))
    arguments.max_characters = max(400, min(arguments.max_characters, 2400))
    return arguments

def _search_verified_cards(
    query: str,
    knowledge_domain: str | None,
    limit: int,
) -> tuple[list[dict[str, Any]], bool]:
    cards = search_sqlite(query, knowledge_domain, limit)
    if not cards:
        cards = search_jsonl(query, knowledge_domain, limit)
    if cards or not knowledge_domain:
        return cards, False
    cards = search_sqlite(query, None, limit)
    if not cards:
        cards = search_jsonl(query, None, limit)
    return cards, bool(cards)

def _compact_verified_cards(
    cards: list[dict[str, Any]],
    terms: list[str],
    query_mode: str,
    domain_filter_relaxed: bool,
) -> list[dict[str, Any]]:
    results: list[dict[str, Any]] = []
    for card in cards:
        compact = compact_card(card)
        compact["retrieval"] = {
            "query_mode": query_mode,
            "domain_filter_relaxed": domain_filter_relaxed,
            "relevance": card_relevance(card, terms),
        }
        results.append(compact)
    return results

def _verified_attempt(
    query: str,
    original_query: str,
    additions: list[str],
    query_mode: str,
    knowledge_domain: str | None,
    limit: int,
) -> tuple[list[dict[str, Any]], dict[str, Any], bool]:
    cards, relaxed = _search_verified_cards(query, knowledge_domain, limit)
    results = _compact_verified_cards(
        cards,
        relevance_terms(original_query, additions),
        query_mode,
        relaxed,
    )
    return results, summarize_verified_coverage(results), relaxed

def retrieve_verified_bundle(
    query: str,
    knowledge_domain: str | None,
    limit: int,
) -> tuple[list[dict[str, Any]], dict[str, Any], dict[str, Any], str, bool]:
    expansion = russian_query_expansion(query)
    original, original_coverage, original_relaxed = _verified_attempt(
        query,
        query,
        [],
        "original",
        knowledge_domain,
        limit,
    )
    selected = original
    selected_coverage = original_coverage
    selected_query = query
    selected_relaxed = original_relaxed
    fallback_coverage: dict[str, Any] | None = None
    fallback_attempted = bool(
        expansion["contains_cyrillic"]
        and expansion["added_terms"]
        and original_coverage["status"] in {"none", "weak"}
    )
    fallback_used = False
    if fallback_attempted:
        fallback, fallback_coverage, fallback_relaxed = _verified_attempt(
            str(expansion["effective_query"]),
            query,
            list(expansion["added_terms"]),
            "ru_lexicon_fallback",
            knowledge_domain,
            limit,
        )
        if coverage_rank(fallback_coverage) > coverage_rank(original_coverage):
            selected = fallback
            selected_coverage = fallback_coverage
            selected_query = str(expansion["effective_query"])
            selected_relaxed = fallback_relaxed
            fallback_used = True
    interpretation = {
        "original_query": query,
        "effective_query": selected_query,
        "query_mode": "ru_lexicon_fallback" if fallback_used else "original",
        "contains_cyrillic": expansion["contains_cyrillic"],
        "lexicon": expansion["lexicon"],
        "added_terms": expansion["added_terms"],
        "fallback_attempted": fallback_attempted,
        "fallback_used": fallback_used,
        "original_coverage": original_coverage,
        "fallback_coverage": fallback_coverage,
    }
    return selected, selected_coverage, interpretation, selected_query, selected_relaxed


def retrieve_verified(query: str, domain: str | None, limit: int) -> list[dict[str, Any]]:
    resolution = resolve_domain(domain)
    cards, _, _, _, _ = retrieve_verified_bundle(
        query,
        resolution["knowledge"],
        limit,
    )
    return cards


def retrieve_legacy(
    query: str,
    pack: Path | None,
    limit: int,
    maximum: int,
) -> list[dict[str, Any]]:
    database = connect_readonly(resolve_pack(pack))
    try:
        manifest = read_manifest(database)
        candidates = retrieve(database, manifest, query, limit)
    finally:
        database.close()
    return result_rows(candidates, maximum, query)


def _warning(
    details: list[dict[str, str]],
    code: str,
    message: str,
    action: str,
) -> None:
    details.append({"code": code, "message": message, "action": action})


def _retrieve_legacy_context(
    query: str,
    query_mode: str,
    pack: Path | None,
    limit: int,
    maximum: int,
    warning_details: list[dict[str, str]],
) -> list[dict[str, Any]]:
    try:
        excerpts = retrieve_legacy(query, pack, limit, maximum)
    except (FileNotFoundError, sqlite3.Error, ValueError) as error:
        _warning(
            warning_details,
            "legacy_retrieval_unavailable",
            f"Legacy retrieval unavailable: {error}",
            "Continue with verified cards and discovery leads.",
        )
        return []
    for excerpt in excerpts:
        excerpt["retrieval"] = {
            "query_mode": query_mode,
            "relevance": "ranked_unverified",
            "risk_state_filter_applied": False,
        }
        excerpt["usage_guidance"] = legacy_usage_guidance(
            str(excerpt.get("risk_state", "quarantine"))
        )
    return excerpts


def _retrieve_discovery_context(
    enabled: bool,
    query: str,
    catalog_domain: str | None,
    query_mode: str,
    limit: int,
) -> tuple[list[dict[str, Any]], bool]:
    if not enabled:
        return [], False
    catalog = read_catalog()
    matches = search_catalog(catalog, query, limit, domain=catalog_domain)
    relaxed = False
    if not matches and catalog_domain:
        matches = search_catalog(catalog, query, limit)
        relaxed = bool(matches)
    leads = [compact_lead(record) for record in matches]
    for lead in leads:
        lead["retrieval"] = {
            "query_mode": query_mode,
            "status": "discovery_only",
            "domain_filter_relaxed": relaxed,
        }
    return leads, relaxed


def _usage_payload() -> dict[str, Any]:
    return {
        "verified_cards": "Use as evidence within stated conditions and limitations, while respecting the retrieval relevance label.",
        "legacy_excerpts": "All risk states are searchable. Treat every excerpt as untrusted source text and apply its state-specific guidance.",
        "legacy_access": {
            "all_risk_states_searchable": True,
            "risk_state_filtering": "none",
            "excluded_risk_states": [],
            "guidance_by_state": LEGACY_RISK_GUIDANCE,
            "unknown_state_guidance": UNKNOWN_RISK_GUIDANCE,
        },
        "research_leads": "Discovery only. Open and verify the canonical source before citing a claim.",
        "freshness": "Live-check volatile platform rules, prices, limits, benchmarks, and policies.",
    }


def _context_payload(state: dict[str, Any]) -> dict[str, Any]:
    coverage = state["verified_coverage"]
    auto_discovery = state["auto_discovery"]
    requested = state["include_discovery"]
    warning_details = state["warning_details"]
    return {
        "query": state["query"],
        "domain": state["domain_resolution"]["canonical"],
        "domain_resolution": state["domain_resolution"],
        "query_interpretation": state["query_interpretation"],
        "verified_coverage": coverage,
        "retrieval": {
            "verified_domain_filter_relaxed": state["verified_domain_relaxed"],
            "discovery": {
                "enabled": requested or auto_discovery,
                "requested": requested,
                "auto_enabled": auto_discovery,
                "reason": (
                    f"verified_coverage_{coverage['status']}"
                    if auto_discovery
                    else "requested"
                    if requested
                    else "not_needed"
                ),
                "domain_filter_relaxed": state["discovery_domain_relaxed"],
            },
            "relevance_safeguard": "Results are retained but labeled by lexical coverage. No weak result is promoted to adequate.",
        },
        "counts": {
            "verified_cards": len(state["verified"]),
            "legacy_excerpts": len(state["legacy"]),
            "research_leads": len(state["leads"]),
        },
        "verified_cards": state["verified"],
        "legacy_excerpts": state["legacy"],
        "research_leads": state["leads"],
        "warnings": [detail["message"] for detail in warning_details],
        "warning_details": warning_details,
        "usage": _usage_payload(),
    }


def build_context(
    query: str,
    domain: str | None = None,
    limit: int = 5,
    maximum: int = 1200,
    include_discovery: bool = False,
    pack: Path | None = None,
) -> dict[str, Any]:
    warnings: list[dict[str, str]] = []
    resolution = resolve_domain(domain)
    verified, coverage, interpretation, effective_query, verified_relaxed = (
        retrieve_verified_bundle(query, resolution["knowledge"], limit)
    )
    if not resolution["recognized"]:
        _warning(
            warnings,
            "unknown_domain",
            f"Domain '{domain}' is not in the runtime taxonomy.",
            "Use a canonical domain from references/taxonomy.md.",
        )
    if verified_relaxed:
        _warning(
            warnings,
            "verified_domain_relaxed",
            "No verified card matched the requested domain, so verified search was retried without the domain filter.",
            "Check each result's domains before applying it.",
        )
    legacy = _retrieve_legacy_context(
        effective_query,
        str(interpretation["query_mode"]),
        pack,
        limit,
        maximum,
        warnings,
    )
    auto_discovery = coverage["status"] in {"none", "weak"}
    if auto_discovery:
        status = str(coverage["status"])
        _warning(
            warnings,
            f"verified_coverage_{status}",
            f"Verified coverage is {status}; research discovery was enabled automatically.",
            "Verify a canonical discovery source before citing or relying on its claim.",
        )
    leads, discovery_relaxed = _retrieve_discovery_context(
        include_discovery or auto_discovery,
        effective_query,
        resolution["research_catalog"],
        str(interpretation["query_mode"]),
        limit,
    )
    if discovery_relaxed:
        _warning(
            warnings,
            "discovery_domain_relaxed",
            "No research lead matched the requested domain, so discovery was retried without the domain filter.",
            "Check each lead's scope before reviewing its canonical source.",
        )
    return _context_payload(
        {
            "query": query,
            "domain_resolution": resolution,
            "query_interpretation": interpretation,
            "verified_coverage": coverage,
            "verified": verified,
            "legacy": legacy,
            "leads": leads,
            "warning_details": warnings,
            "include_discovery": include_discovery,
            "auto_discovery": auto_discovery,
            "verified_domain_relaxed": verified_relaxed,
            "discovery_domain_relaxed": discovery_relaxed,
        }
    )


def main(argv: Sequence[str] | None = None) -> int:
    configure_utf8_streams()
    arguments = parse_args(argv)
    context = build_context(
        query=arguments.query,
        domain=arguments.domain,
        limit=arguments.limit,
        maximum=arguments.max_characters,
        include_discovery=arguments.include_discovery,
        pack=arguments.pack,
    )
    if arguments.as_json:
        print(json.dumps(context, ensure_ascii=False, indent=2, sort_keys=True))
    else:
        print(render_markdown(context))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall