jmdevilleros/niche-map

Mapa de nicho: lacunas em um espaço conceitual

Este skill encontra lacunas bem fundamentadas em um domínio. Ele transforma uma paisagem difusa em uma tabela de itens reais × dimensões explícitas, busca por combinações e zonas que ninguém ocupa, traduz essas lacunas em ideias concretas e verifica se não são miragens.

Princípio norteador. Números organizam o julgamento; não o substituem. Códigos são decisões do analista, então o espaço reflete tanto a rubrica quanto o mercado. É por isso que toda lacuna proposta deve sobreviver a uma verificação de confiabilidade dos códigos (passo 2b) e a uma validação externa (passo 6).

Ferramentas neste repositório

Arquivo	Função
niche_core.py	Passos 3-4: codificação, clusters, PCA, UMAP, lacunas triplas, lacunas de densidade, vizinhos candidatos, oferta vs demanda, figuras
recode_check.py	Passo 2b: amostra de re-codificação cega e concordância por dimensão (kappa de Cohen)
md_to_pdf.py	Passo 7: relatório Markdown para PDF
templates/report_template.md	Passo 7: esqueleto do relatório
examples/	Conjunto de dados sintético e fictício para testar o pipeline de ponta a ponta

---

0. Entradas e perguntas de escopo

Obtenha estas respostas antes de começar. Se alguma estiver faltando, pergunte uma vez, em um único bloco.

Entrada	Pergunta	Por que é importante
Tópico e limite	O que conta como item? (ex.: "ferramentas cujo valor central é X")	Evita categorias mistas e artefatos de lacuna.
N	Quantos itens? (padrão 80-100; mínimo útil ≈ 50)	Com N < 50, as contagens triplas são ruído.
Critérios de inclusão	Recepção mínima, disponibilidade, plataforma, idioma, data	Aplicado no passo 1 e documentado.
Usuário-alvo	Quem construirá ou comprará o que resultar?	Base da pontuação de adequação e de target_filter.
Restrições	Orçamento, horas, habilidades, canal de vendas, tópicos excluídos	Tornam-se target_filter e o critério de adequação.
Entregável	Idioma, moeda (e fonte da taxa de câmbio), formato	Padrão: PDF com classificação, cartões de nicho, mapas e a tabela completa do corpus com links.

1. Corpus: N itens reais e verificados

1. Semente ampla. Colete cerca de 1,3 × N candidatos de fontes variadas: lojas ou diretórios do domínio, listas "melhores", pesquisas "alternativas a X" e lançamentos recentes de cauda longa (sites de lançamento, diretórios de nicho, registros de código aberto). Se apenas produtos famosos entrarem, lacunas falsas aparecerão depois.
2. Verificação de existência por item. Cada item precisa de uma URL que resolva: página da loja, página de preços ou repositório. Registre o status HTTP, a URL final e a data. Se um site bloquear bots (403), verifique a raiz do domínio ou use um navegador; um bloqueio não significa que o item não existe.
3. Sinal de recepção. Registre um ou mais sinais públicos (avaliação da loja e contagem de avaliações, votos em site de lançamento, estrelas do repositório, instalações, prêmios) e declare a fonte e cobertura de cada um. Não descarte um item apenas porque não tem sinal. Se a recepção for um critério de inclusão, aplique-o com um limite explícito.
4. Desduplicação de variantes, rebrandings, edições e SKUs regionais. Mantenha o nome canônico e os links.
5. Exclusão por limite dos itens que falham nos critérios de inclusão, e liste-os no relatório com o motivo.
6. Verificações de viés do corpus (escreva as respostas no relatório):
   • Proporção de itens da cauda longa (ex.: lançados nos últimos 24 meses, ou abaixo do sinal de recepção mediano). Se estiver abaixo de ~20 %, amostre mais itens de cauda longa.
   • Concentração de fontes: nenhuma fonte deve contribuir com mais de ~40 % dos itens.
   • Viés de plataforma ou idioma em relação ao limite declarado.
   • Cobertura de sinal por fonte (algumas fontes super-representam certos tipos de usuário, ex.: ferramentas de desenvolvedor em sites de hospedagem de código).

Saída: items.csv, uma linha por item com colunas de identificação e link, mais um JSON bruto da verificação.

2. Dimensões, escalas e rubrica de codificação

1. Derive 8-15 dimensões lendo uma amostra de cerca de 20 itens. Divida-as em dois tipos:
   • Dimensões conceituais dizem o que o item é: verbo ou ação, entrada, saída, gatilho, domínio ou tema, usuário, estética. As lacunas são pesquisadas com estas (gap_dims).
   • Dimensões de atributo dizem como é construído ou vendido: complexidade, amplitude, autoatendimento, modelo de precificação, faixa de preço. Elas filtram e pontuam. Se usadas na busca de lacunas, produzem lacunas "meta" como "acionado por evento + sem IA + alta complexidade".
2. Escalas. Categorias nominais com 3-14 valores mutuamente exclusivos, cada um com um rótulo legível, ou ordinais curtos (0-1, 0-2, 1-3) com âncoras descritas.
3. Rubrica escrita: uma linha por valor com uma definição e um item de exemplo, mais as regras de decisão abaixo. Ela vai no apêndice do relatório e é o único material que o segundo codificador recebe no passo 2b.
   • Codifique a estrutura lógica, não a aparência. Para dimensões espaciais ou estruturais, codifique como o usuário realmente interage ou raciocina sobre a coisa, não como ela se parece (ex.: um produto renderizado em 3D usado em um plano plano não é "3D").
   • Ordem de precedência para valores sobrepostos. Quando uma escala nominal descreve algo perceptual ou estilístico (aparência, tom, estilo), os valores se sobrepõem. Dê uma ordem de decisão explícita ("se A se aplicar, codifique A; senão se B..."), ou mescle valores que os codificadores não conseguem distinguir.
   • Âncoras mensuráveis para ordinais. Âncoras como duração, tamanho ou esforço devem dizer como medi-las e de que fonte (ex.: "sessão típica conforme descrito na descrição da loja ou observado em um vídeo de demonstração; para itens baseados em níveis, um nível"). Se não puder ser observado, codifique o caso modal e sinalize-o.
   • Codifique o modo principal. Se um item for ambíguo, codifique seu modo principal e anote a dúvida em uma coluna notes.
4. Pesos. Padrão 1,0. Aumente dimensões conceituais centrais (ex.: verbo para 1,2), reduza as periféricas (ex.: modelo de precificação para 0,4). Justifique cada peso.
5. Verificações estruturais:
   • Nenhuma categoria com menos de 2 itens; mescle ou descarte (niche_core.py avisa).
   • Tabelas cruzadas para detectar dimensões redundantes (correlação ≈ 1): descarte ou mescle uma delas.
6. Reconheça os limites: códigos são julgamentos.

Saída: o CSV de itens × dimensões e config.json com escalas, pesos e regras.

2b. Verificação de re-codificação cega (obrigatória)

Objetivo: medir se a rubrica, e não a memória do codificador, determina os códigos. Lacunas construídas em dimensões não confiáveis são artefatos da rubrica.

1. Amostra. Sorteie aleatoriamente 10 % do corpus, mínimo 10 itens, com uma semente fixa: python recode_check.py sample --items items.csv --config config.json --out recode_sheet.csv --keep link A planilha contém apenas o id e link do item, com colunas de dimensão vazias.
2. Segundo codificador, cego. Uma pessoa diferente, ou uma sessão de agente separada que nunca viu os primeiros códigos (sem acesso a items.csv, aos clusters ou ao relatório), codifica a planilha usando apenas a rubrica escrita e as páginas públicas do item. Se o mesmo agente precisar fazer isso, inicie um novo contexto e forneça apenas a planilha e a rubrica. Bloqueie o resultado antes de comparar (ex.: armazene um checksum).
3. Concordância por dimensão: python recode_check.py agree --items items.csv --config config.json --recode recode_sheet.csv --out agreement.csv
   • Dimensões categóricas: kappa de Cohen (κ).
   • Dimensões ordinais: kappa de Cohen ponderado linearmente (κw), que dá crédito parcial para erros próximos.
   • A porcentagem bruta de concordância é relatada junto, mais uma lista de discordância por item.
4. Limiar. Uma dimensão passa com κ (ou κw) ≥ 0,60 e concordância bruta ≥ 80 %. Com n ≈ 10, kappa é ruidoso: use-o para triagem e leia cada discordância.
5. Abaixo do limiar, nesta ordem:
   1. Leia as discordâncias e classifique-as: ambiguidade da rubrica (valores sobrepostos, âncora não mensurável), confusão entre aparência e estrutura, ou erro do codificador.
   2. Corrija a rubrica com uma das regras de decisão do passo 2.3 (ordem de precedência, âncora mensurável, mescle valores que não podem ser distinguidos).
   3. Re-codifique essa dimensão para todo o corpus com a rubrica revisada e, em seguida, re-execute a verificação em uma nova amostra de 10 % (nova semente) para essa dimensão.
   4. Se ainda falhar: reduza seu peso (≤ 0,6), remova-a de gap_dims ou descarte-a. Nunca relate uma lacuna cujo trio explicativo se baseie em uma dimensão que falhou duas vezes.
6. Relate a tabela (dimensão, n, % concordância, κ/κw, status), as alterações na rubrica feitas e o tipo de identidade do segundo codificador (humano, agente separado).

Resultado típico: dimensões sobre função (ação, objetivo, entrada/saída, gatilho) concordam bem; dimensões perceptuais ou estimadas (estilo, estrutura espacial, duração) são as falhas usuais, e é por isso que as regras de decisão no passo 2.3 existem.

3. Espaço: codificação, clusters, gradientes e visualização

Feito por niche_core.py. Regra de ouro: clusters e lacunas são calculados no espaço codificado original; UMAP é apenas para desenho.

• Codificação. One-hot × peso/√2 para dimensões categóricas e (x − min)/(max − min) para ordinais, para que mudar de categoria custe o mesmo que um movimento ordinal de ponta a ponta.
• Clusters. Ward aglomerativo com k escolhido por silhueta dentro de k_range. Um k maior é aceito apenas se melhorar a silhueta em mais de 0,005.
  • Verificação de faixa k: se o k escolhido cair em qualquer borda da faixa, amplie a faixa e execute novamente; o script avisa. Se permanecer na borda, escolha k por interpretabilidade e diga isso.
  • Silhueta entre 0,15 e 0,30 é normal com dados categóricos; não venda como "clusters nítidos".
  • Clusters com < 3 itens e itens com vetores idênticos são sinalizados; estes últimos sugerem uma rubrica muito grosseira para distinguir itens.
  • Nomeie cada cluster manualmente a partir de cluster_profiles.md e armazene os nomes em cluster_names.
• Gradientes. As cargas da PCA (PC1-PC3, pca_loadings.csv) são lidas como eixos "de A a B".
• Visualização. UMAP (n_neighbors 10-15, min_dist 0,25, semente fixa) com um fundo de densidade KDE. Limites:
  • distâncias globais e tamanhos de ilhas não significam nada;
  • transform tende a puxar novos pontos para a ilha mais próxima, portanto a novidade de um candidato é lida a partir de dist_min no espaço original, nunca do gráfico.
• Mapas de calor pareados de dimensões mostram células vazias de relance.

4. Lacunas

4a. Lacunas combinatórias (triplas). Para cada tripla de valores das dimensões de lacuna (conceituais), compare o observado com o esperado sob independência: e = N · p(a) · p(b) · p(c), z = (e − o)/√e. Uma tripla é mantida se:

• o ≤ max_observed (padrão 1);
• e ≥ min_expected (padrão 1,2);
• todo par na tripla aparece em pelo menos min_pair_support itens (padrão 2): as peças existem separadamente;
• toca pelo menos uma dimensão âncora (anchor_dims, ex.: domínio ou verbo).

Filtro de meta-lacuna: mantenha as dimensões de atributo fora de gap_dims e defina anchor_dims para as dimensões que descrevem o conteúdo do produto. Triplas feitas apenas de atributos não são nichos.

4b. Lacunas de densidade. São gerados 50.000-400.000 vetores sintéticos aleatórios e mantidos apenas se:

1. todo par de valores existe em pelo menos um item real (recombinação de peças conhecidas);
2. nenhuma regra de coerência os proíbe (rules: combinações absurdas no domínio);
3. correspondem ao perfil do usuário-alvo (target_filter, ex.: complexidade ≤ 1 e autoatendimento = 1). Este é o filtro de adequação ao usuário: sem ele, as lacunas de densidade derivam para produtos que o usuário não pode construir ou vender.

Os sobreviventes são classificados pela distância ao item real mais próximo e desduplicados nas principais dimensões conceituais (density_dedupe). Compare com a distância mediana do vizinho mais próximo entre itens reais distintos (median_nn_distance).

4c. Oferta vs demanda (opcional). Por cluster: número de itens (oferta) vs a mediana de um sinal de demanda (avaliações, instalações, volume de pesquisa, estrelas), sempre com sua cobertura (supply_demand_clusters.csv). Um cluster pequeno com alta demanda é uma pista de lacuna (inferência).

4d. Pontuação preliminar. Novidade (1-5, da distância relativa e da tripla que explica a lacuna), viabilidade (1-5, esforço do MVP com os recursos do usuário) e adequação (1-5, preferências e restrições do passo 0). Para cada candidato, verifique seus 3 vizinhos mais próximos adicionando-o a candidates e executando novamente.

5. Tradução semântica: do vetor à ideia

Escolha 8-12 candidatos das triplas de maior z e das lacunas de densidade mais distantes; mescle sinais e remova duplicatas. Cada candidato recebe:

• Nome de trabalho e um pitch concreto de 2-3 frases: o que o usuário faz, o que o produto entrega.
• Vetor em todas as dimensões; deve satisfazer as regras.
• Itens mais próximos com distância (× mediana).
• Por que parece vazio no corpus: qual tripla ou zona explica, e se alguma de suas dimensões falhou no passo 2b.
• Riscos: técnicos, de mercado e de adequação.

6. Validação externa e teste de miragem

1. Pesquisa direcionada por candidato, fora do corpus:

   • "[conceito] + app/ferramenta + preço";
   • "alternativa a [conceito]";
   • lojas do domínio com 2-3 sinônimos;
   • repositórios de código aberto.

   Registre 3-5 concorrentes com link e preço. Presuma que alguns quase sempre aparecerão: um corpus de N ≈ 100 não cobre a cauda longa. Ajuste a novidade de acordo.

2. Teste de miragem (adaptado de white-space-analysis, veja Referências). O candidato enfrenta quatro perguntas:

   • Tamanho: há pessoas suficientes com este trabalho a ser feito?
   • Disposição para pagar ou mudar: da evidência mais forte para a mais fraca, elas já pagam por uma solução parcial, mantêm uma solução alternativa cara ou tentaram construir por conta própria.
   • Pergunta do titular: por que ninguém preencheu isso? Respostas aceitáveis: conflito de modelo de negócios ou canal, uma mudança externa recente, um segmento crescente. Resposta alarmante: "Não consigo encontrar uma razão".
   • Capacidade de vencer: o usuário-alvo pode superar a barreira que mantém a lacuna vazia?

   Veredito: passa (fator 1,0), duvidoso (0,7) ou falha (0,4).

3. Pontuação final = novidade × viabilidade × adequação × fator de miragem (faixa 0,4-125).

4. Candidatos que falham na validação permanecem no relatório como "falsas lacunas". Eles expõem viés do corpus e ruído da codificação.