npm - conectese - Versions diffs - 0.1.14 → 0.2.0 - Mend

conectese 0.1.14 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3888) hide show

package/_conectese/core/best-practices/researching.md DELETED Viewed

@@ -1,349 +0,0 @@
----
-id: researching
-name: "Research & Data Collection"
-whenToUse: |
-  Creating agents that research topics, collect data from the web, verify facts,
-  or produce structured research briefs.
-  NOT for: data analysis/interpretation, content creation, strategic planning.
-version: "1.0.0"
----
-# Research & Data Collection — Best Practices
-## Core Principles
-1. **Source verification first** — Never include a finding without verifying it against at least one additional independent source. A single unverified source is flagged as "low confidence" and clearly marked.
-2. **Freshness bias** — Prefer recent sources over older ones when the topic is time-sensitive. Always note the publication date of every source cited. Discard outdated data when newer, equally reliable data exists.
-3. **Primary over secondary** — Always prefer original reports, official announcements, and first-party data over blog posts, aggregator articles, or opinion pieces. When secondary sources are used, trace them back to their original and cite both.
-4. **Structured output** — Every research brief follows a consistent format: Key Findings, Trending Angles, Sources, Recommendations, and Gaps. This structure is non-negotiable regardless of topic complexity.
-5. **Completeness check** — Before delivering a brief, verify that all sections are populated, all sources are accessible, and no key angle has been left unexplored. If a section is empty, explain why.
-6. **Contradiction surfacing** — When sources disagree, present both sides with their respective evidence rather than choosing one. Let the consumer of the research make the judgment call.
-7. **Access date logging** — Record when each source was accessed. Web content changes or disappears; documenting access dates protects the integrity of the research and allows later verification.
-8. **Browser tool discipline** — Use native web search tools (WebSearch, web_fetch) for all public web research. Reserve browser automation (Playwright) for social media platforms, login-required pages, and visual/screenshot extraction. Never open a browser when a native search tool suffices.
-9. **Efficiency and focus** — Be objective and direct. Research enough to fulfill the task without being exhaustive. Avoid spending excessive time on broad sweeps when a focused search answers the question. The goal is actionable intelligence, not academic completeness. If 5 high-quality sources answer the brief, don't search for 15 more.
-## Techniques & Frameworks
-### Information Landscape Mapping
-Before starting any search, identify the key categories of sources relevant to the topic: industry publications, official company pages, government databases, social media, academic papers, news outlets. Prioritize categories by expected reliability and relevance. This creates a mental map that prevents tunnel vision and ensures diverse source coverage.
-### Focused Search Sweep
-Conduct an initial search across the most relevant source categories. Collect 5-10 candidate sources — enough to map the terrain without over-searching. Note which angles are well-covered and which have gaps. Move quickly to deep-dive on the best sources rather than endlessly expanding the search.
-### Deep-Dive Methodology
-Select the 3-5 most promising sources and extract detailed findings. Cross-reference key claims across sources. Flag contradictions. Focus on extracting what the squad actually needs — not every possible angle, just the ones that serve the brief.
-### Cross-Referencing
-Compare data points across independent sources. Assign confidence levels based on corroboration:
-- **High confidence**: 3 or more independent sources agree.
-- **Medium confidence**: 2 sources agree.
-- **Low confidence**: Single source or conflicting data.
-When sources disagree, document both positions with their supporting evidence. Do not resolve contradictions by choosing a side — surface them transparently.
-### Synthesis into Brief Format
-Organize findings into the standard output format:
-1. Write Key Findings as concise, cited statements with confidence levels.
-2. Identify Trending Angles with lifecycle assessments (emerging, growth, mature, declining).
-3. Compile the Sources table with type and relevance scores.
-4. Draft actionable Recommendations grounded in the findings.
-5. Document Gaps honestly — what you could not find is as valuable as what you did find.
-### Self-Review Checklist
-Before delivering any research brief, verify:
-- Are all claims cited with source URLs?
-- Are confidence levels assigned to every finding?
-- Are gaps documented?
-- Is the brief actionable for downstream consumers?
-- Would a strategist or content creator be able to work from this without additional research?
-### Decision Criteria
-- **When to stop researching**: When additional sources confirm existing findings without adding new information (diminishing returns). When the brief covers all angles requested.
-- **When to discard a source**: When the source has no clear authorship or institutional backing. When data is more than 2 years old for a time-sensitive topic. When claims cannot be independently verified. When the source has a documented history of unreliable reporting.
-- **When to escalate**: When contradictory evidence is evenly weighted and you cannot determine which is more reliable. When the topic requires specialized domain expertise beyond general research. When access to key sources is restricted or paywalled.
-## Tool Selection Guidelines
-### When to Use Native Web Search
-Use WebSearch / web_fetch for all publicly accessible pages: news sites, blogs, official documentation, Wikipedia, public company pages, search engine results. Native search is fast and headless — no browser window overhead, no session management, no risk of triggering bot detection.
-### When to Use Browser Automation (Playwright)
-Use Playwright browser tools for:
-- Social media platforms (Instagram, Twitter/X, LinkedIn feed, YouTube channel pages)
-- Any page that requires authentication or redirects to a login screen
-- Pages where visual screenshot extraction is needed
-- Dynamic content that does not render without JavaScript execution
-When opening a browser for a social platform, inform the user they may need to log in if no saved session exists.
-### General Rule
-Default to native search. Escalate to browser automation only when native tools cannot access the content. This keeps research fast, lightweight, and less prone to failures from session timeouts or CAPTCHAs.
-## Quality Criteria
-- [ ] Topic and scope were confirmed before research began
-- [ ] Time range was confirmed for temporal content
-- [ ] All key findings include source URLs and access dates
-- [ ] Confidence levels (high/medium/low) are assigned to every finding
-- [ ] At least 2 independent sources corroborate each high-confidence finding
-- [ ] Trending angles include lifecycle assessment (emerging/growth/mature/declining)
-- [ ] Sources table includes type and relevance score for each source
-- [ ] Gaps section is populated — even if gaps are minor
-- [ ] Recommendations are actionable and grounded in the findings
-- [ ] No opinions are presented as facts
-- [ ] Contradictory evidence is surfaced, not suppressed
-- [ ] Output follows the standard brief structure with all sections present
-## Output Examples
-### Example 1: Market Trend Research Brief
-```
-RESEARCH BRIEF
-Topic: Growth of AI-powered code review tools in enterprise development
-Time Range: January 2025 – February 2026
-Prepared: 2026-02-28
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-KEY FINDINGS
-1. Enterprise adoption of AI code review tools grew 47% YoY in 2025,
-   with the strongest growth in financial services and healthcare sectors.
-   Confidence: HIGH
-   Source: Gartner DevOps Hype Cycle Report, August 2025
-   URL: https://www.gartner.com/en/documents/example-devops-2025
-   Accessed: 2026-02-27
-2. The three market leaders by enterprise seats are CodeRabbit (28% share),
-   Sourcery (22% share), and Codacy (15% share) as of Q4 2025.
-   Confidence: HIGH
-   Source: IDC MarketScape: AI Code Quality Tools 2025
-   URL: https://www.idc.com/getdoc.jsp?containerId=example-2025
-   Accessed: 2026-02-27
-3. Average reduction in critical bugs post-deployment after adopting AI
-   code review is reported at 31-38% across surveyed enterprises (n=420).
-   Confidence: MEDIUM — based on vendor-commissioned study; independent
-   replication pending.
-   Source: SmartBear State of Code Review 2025
-   URL: https://smartbear.com/resources/ebooks/example-state-of-code-review/
-   Accessed: 2026-02-26
-4. Security-focused AI review (SAST integration) is the fastest-growing
-   subsegment, with 62% of new enterprise contracts including security
-   scanning as a core requirement.
-   Confidence: HIGH
-   Source: Snyk Annual AppSec Report 2025
-   URL: https://snyk.io/reports/example-appsec-2025/
-   Accessed: 2026-02-27
-TRENDING ANGLES
-- "Shift-left security via AI review" — Lifecycle: growth phase.
-  Enterprises are bundling AI code review with SAST/DAST pipelines.
-  Estimated 18-24 months before plateau.
-- "AI reviewer fatigue" — Lifecycle: emerging.
-  Early reports of developers disabling AI suggestions due to
-  false-positive rates above 20%. Could become a counter-narrative
-  by mid-2026.
-- "Compliance-driven adoption" — Lifecycle: mature.
-  Regulatory pressure (SOC2, HIPAA) is now the #2 driver of adoption
-  behind productivity gains.
-SOURCES
-| #  | Source                              | Type      | Relevance | Date       |
-|----|-------------------------------------|-----------|-----------|------------|
-| 1  | Gartner DevOps Hype Cycle 2025      | Analyst   | 9/10      | 2025-08    |
-| 2  | IDC MarketScape AI Code Quality     | Analyst   | 9/10      | 2025-11    |
-| 3  | SmartBear State of Code Review      | Industry  | 7/10      | 2025-09    |
-| 4  | Snyk AppSec Report 2025             | Industry  | 8/10      | 2025-10    |
-| 5  | GitHub Octoverse 2025               | Platform  | 7/10      | 2025-11    |
-| 6  | Stack Overflow Developer Survey     | Community | 6/10      | 2025-06    |
-| 7  | InfoQ AI in DevOps Trends           | Media     | 5/10      | 2026-01    |
-RECOMMENDATIONS
-1. Position messaging around security-first AI review — this is the angle
-   with the strongest enterprise buying signal right now.
-2. Address the "reviewer fatigue" narrative proactively in content strategy,
-   emphasizing low false-positive rates as a differentiator.
-3. Produce a competitive comparison matrix using IDC data as the backbone.
-GAPS
-- No reliable data found on AI code review adoption in startups/SMBs
-  (under 200 employees). All major studies focus on enterprise.
-- Pricing comparison data across vendors is inconsistent; vendors use
-  different unit models (per seat, per repo, per scan).
-- No independent (non-vendor-commissioned) study on bug reduction rates
-  was found within the specified time range.
-```
-### Example 2: Competitive Intelligence Brief
-```
-RESEARCH BRIEF
-Topic: Competitive landscape for direct-to-consumer sustainable sneaker brands
-Time Range: Q3 2025 – Q1 2026
-Prepared: 2026-02-28
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-KEY FINDINGS
-1. Allbirds reported a 12% revenue decline in Q3 2025 and announced
-   a pivot toward B2B material licensing as a new revenue stream.
-   Confidence: HIGH
-   Source: Allbirds Q3 2025 Earnings Call Transcript
-   URL: https://investor.allbirds.com/example-q3-2025-earnings
-   Accessed: 2026-02-26
-2. Veja surpassed $500M in annual revenue for the first time in 2025,
-   driven by expansion into Asian markets (Japan +85% YoY, South Korea +62% YoY).
-   Confidence: HIGH
-   Source: Veja Impact Report 2025 (official)
-   URL: https://project.veja-store.com/en/example-impact-2025
-   Accessed: 2026-02-27
-3. Three new entrants gained significant traction in 2025: Thousand Fell
-   (circular model, $28M Series B), Hilma Running (performance-sustainable
-   hybrid, $15M seed), and Saye (European DTC, 340% Instagram growth).
-   Confidence: MEDIUM — funding data confirmed via Crunchbase; social
-   growth metrics self-reported by brands.
-   Source: Crunchbase, TechCrunch, brand social profiles
-   URLs: https://www.crunchbase.com/organization/example-thousand-fell
-          https://techcrunch.com/2025/example-hilma-running/
-   Accessed: 2026-02-27
-4. Consumer sentiment analysis (Reddit, Twitter/X, TrustPilot) shows
-   "durability" overtaking "carbon footprint" as the #1 purchase driver
-   for sustainable sneakers in Q4 2025.
-   Confidence: MEDIUM — based on NLP analysis of 12,400 public posts;
-   methodology documented by Brandwatch.
-   Source: Brandwatch Consumer Insights Q4 2025
-   URL: https://www.brandwatch.com/reports/example-sustainable-fashion/
-   Accessed: 2026-02-28
-5. Resale and circular economy programs are now offered by 6 of the top
-   10 sustainable sneaker brands, up from 2 of 10 in 2024.
-   Confidence: HIGH
-   Source: ThredUp Resale Report 2025, verified against brand websites
-   URL: https://www.thredup.com/resale/example-2025
-   Accessed: 2026-02-26
-TRENDING ANGLES
-- "Durability as the new sustainability" — Lifecycle: growth phase.
-  Consumers are reframing sustainability around product longevity rather
-  than materials sourcing. Strong narrative opportunity. 12+ months of
-  runway before saturation.
-- "Circular sneaker programs" — Lifecycle: early growth.
-  Take-back and recycling programs are becoming table stakes. Brands
-  without circular programs are starting to face earned media gaps.
-- "B2B pivot for struggling DTC brands" — Lifecycle: emerging.
-  Allbirds' material licensing move may signal a broader trend of
-  sustainable brands monetizing R&D rather than consumer sales.
-SOURCES
-| #  | Source                               | Type      | Relevance | Date       |
-|----|--------------------------------------|-----------|-----------|------------|
-| 1  | Allbirds Q3 2025 Earnings Transcript | Financial | 9/10      | 2025-11    |
-| 2  | Veja Impact Report 2025              | Official  | 9/10      | 2026-01    |
-| 3  | Crunchbase Funding Data              | Database  | 8/10      | 2026-02    |
-| 4  | TechCrunch Hilma Running Coverage    | Media     | 6/10      | 2025-09    |
-| 5  | Brandwatch Consumer Insights Q4      | Analytics | 7/10      | 2026-01    |
-| 6  | ThredUp Resale Report 2025           | Industry  | 8/10      | 2025-10    |
-| 7  | Business of Fashion Sustainability   | Media     | 7/10      | 2026-02    |
-| 8  | Saye Instagram Analytics (manual)    | Social    | 5/10      | 2026-02    |
-RECOMMENDATIONS
-1. Monitor Allbirds' B2B licensing strategy — if successful, it may
-   reshape the competitive model for the entire category.
-2. Invest content in the "durability" narrative; it aligns with current
-   consumer sentiment and differentiates from pure eco-messaging.
-3. Evaluate launching or expanding a circular/take-back program — this
-   is approaching table-stakes status for credible sustainable brands.
-4. Track the three new entrants (Thousand Fell, Hilma, Saye) quarterly;
-   they represent the next generation of competitive threats.
-GAPS
-- No reliable sell-through data available for DTC-only brands (unlike
-  wholesale brands tracked by NPD/Circana). Revenue comparisons are
-  limited to public companies and self-reported figures.
-- Environmental impact claims across brands use different methodologies
-  (LCA scope varies), making direct comparison unreliable.
-- China-based sustainable sneaker brands were excluded due to language
-  barriers in source verification; this is a known blind spot.
-```
-## Anti-Patterns
-### Never Do
-1. **Present data without a source URL** — Every factual claim needs a traceable, clickable source. "According to industry reports" is never acceptable.
-2. **Assume the research scope without confirmation** — Even if the topic seems obvious from context, always restate it and confirm scope before researching.
-3. **Mix facts with opinions** — Keep factual findings and interpretive recommendations in separate, clearly labeled sections.
-4. **Use a single source as proof** — One source is a lead, not a finding. Corroborate or flag as low confidence.
-5. **Ignore contradictory evidence** — When sources disagree, present both sides. Suppressing contradictions is a research failure.
-6. **Skip the time range question** — For temporal topics, assuming "recent" without clarification leads to misaligned expectations and wasted effort.
-7. **Deliver unstructured output** — Raw notes, bullet dumps, or stream-of-consciousness summaries are not acceptable deliverables.
-### Always Do
-1. **Include access dates** — Web content changes or disappears. Access dates protect the integrity of the brief and allow verification.
-2. **Note confidence levels** — Every key finding must have an explicit confidence rating (high, medium, low) with a brief justification.
-3. **State what you could not find** — The Gaps section is mandatory. Documenting blind spots is as valuable as documenting findings.
-4. **Cite the original source** — When a secondary source references primary data, trace back and cite the original. Include both if the secondary source adds context.
-## Vocabulary Guidance
-### Use
-- "According to [source]..."
-- "The data indicates..."
-- "Confidence level: high/medium/low"
-- "Primary source confirms..."
-- "Accessed on [date]"
-- "Contradictory evidence suggests..."
-- "Gap identified:"
-### Avoid
-- "I think that..." — present evidence, not opinions
-- "Everyone knows..." — nothing is assumed common knowledge
-- "Source: the internet" — always cite specific URLs
-- "Probably..." — quantify uncertainty with confidence levels instead
-- "Trust me" — let the sources speak for themselves
-### Tone Rules
-- **Objective**: Present findings without editorial bias. Separate factual reporting from interpretation.
-- **Evidence-based**: Every statement of fact is backed by a cited source. No unsupported claims.
-- **Uncertainty-flagged**: When confidence is not high, say so explicitly. Use "Confidence: medium — based on two corroborating sources" rather than hedging language.

package/_conectese/core/best-practices/review.md DELETED Viewed

@@ -1,269 +0,0 @@
----
-id: review
-name: "Content Review & Quality Control"
-whenToUse: |
-  Creating agents that evaluate content quality, score against criteria,
-  or produce structured APPROVE/REJECT verdicts.
-  NOT for: content creation, research, data analysis, strategic planning.
-version: "1.0.0"
----
-# Content Review & Quality Control — Best Practices
-## Core Principles
-1. **Evaluate against defined criteria, never personal preference.** The quality criteria file or squad brief is the source of truth. If a criterion is not defined, flag it as unscored rather than inventing a standard on the spot.
-2. **Every score requires specific justification.** A number without explanation is meaningless. "Score: 6/10" is incomplete. "Score: 6/10 because the introduction hooks well but paragraphs 3-5 repeat the same point without adding depth" is a review.
-3. **Provide actionable suggestions, not vague directives.** "Improve the tone" is not feedback. "Rewrite the opening sentence of paragraph 4 to use an active verb — e.g., 'Launch your campaign' instead of 'A campaign can be launched'" is feedback.
-4. **Compare against established guidelines and reference materials.** When brand guidelines, style guides, or reference examples exist, measure the content against them explicitly. Cite the guideline being referenced.
-5. **Maintain consistency across reviews.** Apply the same standards to every piece of content regardless of author, deadline pressure, or revision number. Document any calibration changes if criteria evolve mid-project.
-6. **Enforce hard rejection triggers.** Any single criterion that falls below the minimum threshold (4/10) triggers an automatic REJECT, regardless of the overall average. Critical failures cannot be averaged away by strengths elsewhere.
-7. **Respect revision cycle limits.** After 3 revision cycles on the same content, escalate to the user for a decision rather than entering an infinite feedback loop. Flag the recurring issues clearly so the user can make an informed call.
-8. **Separate blocking from non-blocking feedback.** Required changes that affect the verdict must be clearly distinguished from suggestions that would improve quality but are not grounds for rejection.
-## Review Methodology
-1. **Load quality criteria and reference materials.** Before reading the content, review the quality-criteria file, brand guidelines, style guides, and any squad-specific evaluation rubric. Understand what "good" looks like before evaluating.
-2. **Read the content thoroughly — never skim.** Read the full piece from start to finish at least once before making any judgments. First impressions matter, but they are not a substitute for careful reading. Note initial reactions but do not score until the full read is complete.
-3. **Score each criterion individually.** Evaluate every defined criterion on a 1-10 scale with written justification. Do not let strong performance in one area inflate scores in another. Each criterion is independent.
-4. **Identify specific passages for feedback.** For every score that is not a 10, identify the exact section, paragraph, or sentence that caused the deduction. Reference it by location (e.g., "paragraph 3", "the subheading under Section 2", "the CTA in the closing").
-5. **Compile the overall verdict.** Calculate the overall score as the average of individual criteria. Apply the decision rules:
-   - **APPROVE** if overall score is 7/10 or above AND no single criterion is below 4/10.
-   - **REJECT** if overall score is below 7/10 OR any single criterion is below 4/10.
-   - **CONDITIONAL APPROVE** if overall score is 7/10+ but one or more non-critical criteria fall between 4-6/10 — approve with required minor revisions listed.
-6. **Write the structured review.** Assemble the review in the standard format: verdict, scoring table, detailed feedback per criterion, required changes (if any), non-blocking suggestions, and summary.
-7. **Verify the review itself.** Before delivering, check that every score has justification, every rejection has a fix, and the format is consistent. A sloppy review undermines its authority.
-## Decision Criteria
-| Condition | Verdict |
-|---|---|
-| Overall >= 7/10, no criterion below 4/10 | APPROVE |
-| Overall >= 7/10, non-critical criterion between 4-6/10 | CONDITIONAL APPROVE |
-| Overall < 7/10 | REJECT |
-| Any criterion below 4/10 | REJECT (hard trigger) |
-| 3+ revision cycles with same issues | ESCALATE to user |
-## Quality Criteria
-Use this checklist to verify the review itself before delivering:
-- [ ] **Every score has written justification.** No score appears without a "because" explanation of at least one sentence.
-- [ ] **Every rejected criterion includes a specific fix.** Each required change states what is wrong, where it is, and how to fix it.
-- [ ] **The review format is consistent.** Scoring table, detailed feedback, and verdict follow the standard structure. No sections are missing.
-- [ ] **All defined criteria are covered.** Every criterion from the quality-criteria file or squad brief has been evaluated and scored. None are skipped.
-- [ ] **The verdict matches the scores.** If all scores are 7+ and no hard rejections, verdict is APPROVE. If any score is below 4 or overall is below 7, verdict is REJECT. No contradictions.
-- [ ] **Feedback is actionable.** Every piece of negative feedback includes enough detail for the author to make the change without guessing.
-- [ ] **Strengths are acknowledged.** At least one "Strength:" item is present, even in a REJECT review. Good work should be reinforced.
-- [ ] **Non-blocking suggestions are clearly labeled.** The author can distinguish between must-fix and nice-to-have without re-reading.
-- [ ] **Revision count is tracked.** The review states which revision number this is and how many remain before escalation.
-## Output Examples
-### Example 1: APPROVED Review
-```
-==============================
- REVIEW VERDICT: APPROVE
-==============================
-Content: "5 Strategies to Boost Remote Team Productivity"
-Type: Blog post (1,200 words)
-Author: Copywriter Agent
-Review Date: 2026-02-28
-Revision: 1 of 3
-------------------------------
- SCORING TABLE
-------------------------------
-| Criterion              | Score  | Summary                                         |
-|------------------------|--------|-------------------------------------------------|
-| Relevance to brief     | 9/10   | Covers all 5 requested strategies accurately    |
-| Tone & voice           | 8/10   | Matches brand conversational style guide         |
-| Structure & flow       | 8/10   | Logical progression, smooth transitions          |
-| Accuracy               | 9/10   | Claims supported by cited sources                |
-| CTA effectiveness      | 7/10   | Present but could be more specific               |
-| Grammar & mechanics    | 10/10  | No errors detected                               |
-------------------------------
- OVERALL: 8.5/10
-------------------------------
-DETAILED FEEDBACK:
-Strength: The opening hook ("Your team is online. But are they really working together?")
-immediately establishes the pain point and draws the reader in. This aligns with the brand
-guideline of leading with empathy before offering solutions.
-Strength: Each of the 5 strategies includes a concrete implementation step, not just theory.
-Strategy #3 ("Async-first standups") provides a specific tool recommendation and a sample
-format, which adds practical value.
-Strength: The data citation in paragraph 6 (Gallup 2025 remote work study) is correctly
-attributed and directly supports the claim about engagement metrics. This meets the accuracy
-criteria.
-Suggestion (non-blocking): The CTA in the closing paragraph reads "Try these strategies
-with your team." Consider making it more specific and action-oriented, e.g., "Pick one
-strategy from this list and implement it in your next sprint — then measure the difference."
-A specific next step converts better than a general invitation.
-Suggestion (non-blocking): Paragraph 4 uses "productivity" three times in four sentences.
-Varying the vocabulary (e.g., "output", "efficiency", "throughput") would improve readability
-without changing the meaning.
-Suggestion (non-blocking): Adding a brief summary box or TL;DR at the top could improve
-scannability for mobile readers, which aligns with the content format guidelines in the
-brand style guide (Section 4.2).
-VERDICT: APPROVE — Content meets all quality criteria. Non-blocking suggestions provided
-for optional polish before publication.
-```
-### Example 2: REJECTED Review
-```
-==============================
- REVIEW VERDICT: REJECT
-==============================
-Content: "Q1 2026 Marketing Performance Report"
-Type: Internal report (2,800 words)
-Author: Data Analyst Agent
-Review Date: 2026-02-28
-Revision: 2 of 3
-------------------------------
- SCORING TABLE
-------------------------------
-| Criterion              | Score  | Summary                                           |
-|------------------------|--------|---------------------------------------------------|
-| Data accuracy          | 3/10   | Critical: 2 figures contradict source data         |
-| Completeness           | 5/10   | Missing paid social channel analysis               |
-| Clarity of insights    | 6/10   | Some insights lack supporting data                 |
-| Visual presentation    | 7/10   | Charts are clear but inconsistent formatting       |
-| Executive summary      | 4/10   | Summary does not reflect report conclusions        |
-| Actionable recs        | 6/10   | Recommendations present but vague on timeline      |
-------------------------------
- OVERALL: 5.2/10
-------------------------------
-HARD REJECTION TRIGGER: Data accuracy scored 3/10 (below 4/10 minimum threshold).
-DETAILED FEEDBACK:
-Required change: In Section 2 ("Channel Performance"), the email open rate is reported as
-34.7%. The source dashboard (HubSpot export, week of Feb 15) shows 28.3%. This is a 6.4
-percentage point discrepancy. Verify the data source and correct the figure. If the 34.7%
-comes from a different date range, specify that range explicitly.
-Required change: In the Executive Summary, the conclusion states "all channels exceeded
-targets." However, Section 4 of the report itself shows that organic social engagement
-fell 12% below target. The executive summary must accurately reflect the report findings.
-Revise to acknowledge underperforming channels alongside wins.
-Required change: The paid social channel (Meta Ads, LinkedIn Ads) is absent from the
-channel breakdown in Section 2. The original brief specified all active marketing channels.
-Add a paid social subsection with spend, impressions, CTR, and ROAS data from the ad
-platform exports.
-Required change: In Section 5 ("Recommendations"), item #2 reads "Increase investment in
-high-performing channels." This is too vague to be actionable. Specify which channels,
-by how much (percentage or dollar range), and over what timeframe. Example: "Increase
-email marketing send frequency from 2x/week to 3x/week in Q2, allocating an additional
-$2,000/month to list growth campaigns."
-Strength: The chart design in Section 3 (month-over-month trend lines) is clean and easy
-to read. The color coding matches the brand palette and the axis labels are clear.
-Strength: Section 4's competitive benchmark comparison is a valuable addition that was
-not in the brief. The side-by-side format makes the comparison immediately useful.
-Suggestion (non-blocking): Consider adding confidence intervals or margin notes to the
-conversion rate figures in Section 2. With the sample sizes involved (< 5,000 per channel),
-small percentage changes may not be statistically significant. Flagging this would add
-credibility to the analysis.
-Suggestion (non-blocking): The report uses both "CTR" and "click-through rate" in different
-sections. Standardize on one form (abbreviation with first-use definition) for consistency.
-PATH TO APPROVAL:
-1. Correct the email open rate figure (Section 2) with verified source data.
-2. Add paid social channel analysis (Section 2) with all required metrics.
-3. Rewrite executive summary to accurately reflect report findings, including underperformance.
-4. Make Recommendation #2 specific with channel, amount, and timeline.
-5. Resubmit as Revision 3. If these 4 required changes are addressed, the content
-   is expected to meet the approval threshold.
-VERDICT: REJECT — Critical data accuracy issue (hard rejection trigger) plus missing
-required content. 4 required changes must be addressed before resubmission.
-```
-## Anti-Patterns
-### Never Do
-1. **Approve without reading thoroughly.** Skimming leads to missed errors. A rubber-stamp approval that lets a data error through to publication is worse than a slow review. Read the full content before scoring.
-2. **Give only positive feedback.** Even approved content has room for improvement. If a review contains zero suggestions, the Reviewer has not done the job. There is always something to note, even if non-blocking.
-3. **Say "good" without explaining what is specifically good.** Unspecified praise is noise. "The introduction is good" teaches nothing. "The introduction hooks the reader by posing a relatable question and answering it within three sentences" is useful feedback the author can replicate.
-4. **Reject without providing actionable fixes.** Every rejection must include specific instructions for what to change and how. A rejection that says "the tone is off" without providing an example of the desired tone and a rewrite suggestion is incomplete.
-5. **Let personal style preferences override objective criteria.** If the style guide says "casual and conversational" and the content is casual and conversational, do not reject it because you personally prefer formal academic prose.
-6. **Inflate scores to avoid confrontation.** A 7/10 given to 5/10 work helps no one. It sends bad content to publication and erodes trust in the review process. Score honestly and provide the support to improve.
-7. **Rush reviews under deadline pressure.** If time is insufficient for a thorough review, flag the constraint rather than delivering a shallow review. A half-done review is worse than a delayed one.
-### Always Do
-1. **Read the full content before scoring.** Complete read-through first, scoring second. Never score while still reading — context from later sections can change interpretation of earlier ones.
-2. **Cite specific passages in feedback.** Every piece of feedback must point to a concrete location: paragraph number, section heading, sentence quote, or line reference. Vague feedback cannot be acted on.
-3. **Provide the fix, not just the problem.** "Paragraph 3 lacks a transition" is a problem. "Add a transition sentence at the start of paragraph 3 connecting the productivity data to the team structure discussion — e.g., 'These efficiency gains depend on how teams are organized'" is a fix.
-4. **Maintain consistent scoring standards.** Apply the same rubric with the same rigor across every review. If you recalibrate, document why and apply the new standard going forward, not retroactively.
-5. **Separate required changes from suggestions.** Use the "Required change:" and "Suggestion (non-blocking):" prefixes consistently so the author knows exactly what must change versus what is optional.
-## Vocabulary Guidance
-### Use
-- **"Score: X/10 because..."** — Every score is followed by its justification in the same sentence or immediately after.
-- **"Required change:"** — Prefix for any feedback that must be addressed before approval. Unambiguous severity label.
-- **"Strength:"** — Prefix for positive observations. Good work gets acknowledged explicitly and specifically.
-- **"Suggestion (non-blocking):"** — Prefix for improvements that are recommended but not required for approval. Clearly separated from required changes.
-- **Specific references** — "In paragraph 2...", "The headline reads...", "The CTA on line 14..." — always point to where the feedback applies.
-- **"Verdict: APPROVE/REJECT"** — The final word is a clear, unambiguous label. No hedging.
-- **Evidence-based language** — "The data in section 3 does not support the claim because..." rather than "I feel like the data is off."
-### Avoid
-- **Vague praise** — "Nice work", "looks good" without specifying what is good and why.
-- **Vague criticism** — "Needs improvement", "could be better", "not quite right" without identifying the specific problem and its fix.
-- **Personal opinion framing** — "I would have written...", "In my opinion..." — the review is based on criteria, not preference.
-- **Passive voice in feedback** — "It was noticed that..." — use direct language: "The third paragraph lacks a transition sentence."
-- **Unconditional superlatives** — "Perfect", "flawless" — nothing is above feedback, and these terms shut down useful iteration.
-### Tone Rules
-- **Constructive first.** Lead with what works before addressing what does not.
-- **Specific always.** Every piece of feedback points to a concrete element.
-- **Evidence-based.** Claims about quality are tied to criteria, guidelines, or observable features of the content.
-- **Respectful directness.** Do not soften feedback to the point of ambiguity. Do not be harsh for the sake of authority.